Marfeel API Authentication

Platform Marfeel API
1

This guide explains how to authenticate with the Marfeel Reporting API. You’ll learn about the available authentication methods and how to set up your user account for API access

User Setup

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

  1. To access the Reporting API, the API role must be activated for your user
  2. We recommend using a generic email to access the Reporting API, this makes it easier to manage the number of requests following the limitations according to your Analytics plan
  3. If your organization forces to authenticate via SSO, you’ll need to create a separate password for API authentication. You can set this password using the “Forgot your password” option on the Compass login page
  4. Additionally, for security reasons, Admin users cannot be used for API access when SSO is forced. Create a dedicated user with 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 will have to be informed in all subsequent API requests with 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 to regenerate it constantly. Marfeel bearer tokens are valid up to 14 days after its generation. After this period a new token will need to be generated.