Marfeel API authentication with bearer tokens

All Marfeel API endpoints require bearer token authentication (OAuth 2.0). This guide explains the available authentication methods, how to set up your user account for API access, and how to generate and use bearer tokens with the Marfeel Reporting API.

User setup

Before you start using the Marfeel Reporting API, make sure your account meets these requirements:

1. The API role must be activated for your user account
2. Use a generic email to access the Reporting API, as this makes it easier to manage request limits according to your Analytics plan
3. If your organization forces authentication via SSO, you need to create a separate password for API authentication. Set this password using the “Forgot your password” option on the Compass login page
4. For security reasons, Admin users cannot be used for API access when SSO is forced. Create a dedicated user with the API role instead

Authentication methods

All Marfeel API endpoints are authenticated using a bearer HTTP authentication scheme, also called token authentication scheme. The bearer token allowing access to a certain resource or URL is a cryptic string that you generate using a script like a curl command.

A bearer token allows developers to have a more secure point of entry for using the Marfeel APIs, and are one of the core features of OAuth 2.0.

The API client must always send the bearer token in the Authorization header when making requests to protected resources:

Authorization: Bearer <token>

How to generate an API authorization token

You can generate Bearer Tokens via login request using API credentials:

curl --location --request POST 'https://api.newsroom.bi/api/user/signin' \
--header 'Content-Type: application/json' \
--data-raw '{
    "email": "compass.api@youraccount.com",
    "password": "secret"
}'

Here is what the response would look like. See the token field. Note that this is an example Bearer Token:

{
   "id":000,
   "name":"API User",
   "surname":" ",
   "email":"compass.api@youraccount.com",
   "registered":"2021-10-22T09:24:19.000Z",
   "langIso":null,
   "timezoneId":null,
   "dataRules":null,
   "sitesId":000,
   "updatedAt":"2021-11-04T13:31:15.000Z",
   "Timezone":null,
   "Site":{
     "...":"..."
   },
   "token":"eyJ...t0y20",
   "role":""
}

On OSX you can copy the bearer token directly to your clipboard using:

curl --location --request POST 'https://api.newsroom.bi/api/user/signin' \
--header 'Content-Type: application/json' \
--data-raw '{
    "email": "compass.api@youraccount.com",
    "password": "secret"
}' | jq ."token" | pbcopy

TIP: You can you use jq to pretty print the output of the json or to directly select the token field.

How to authorize API requests

Once obtained, the bearer token must be included in all subsequent API requests using the Authorization header:

curl --location --request POST 'https://api.newsroom.bi/api/dashboard/query' \
--header 'Authorization: Bearer eyJ...t0y20' \

Renew tokens

A valid bearer token keeps the authentication alive without requiring constant regeneration. Marfeel bearer tokens are valid for up to 14 days after generation. After this period, a new token must be generated.