Authentication and authorization

Overview

SCALAR APIs use modern security standards to ensure the highest security levels. Authentication is performed by using bearer tokens to authenticate requests. To call an API you need to send the bearer token in the HTTP Authorization request header as shown below:

curl --request GET \
     --url https://trailer.api.eu1.scalar.zf.com/v1/assets \
     --header 'Accept: application/json' \
     --header 'Authorization: Bearer <YOUR_ACCESS_TOKEN>'

Please read the sections below to get a token with the right permissions for you requirements.

Integrator and permissions

An integrator is provided with necessary permissions to enable access to certain endpoints. Each endpoint has authorization in place that will verify if the integrator has permission to access the endpoint. If the integrator does not have enough permissions that the developer needs to do their integration work, the developer will need to ask a more privileged user (or integrator) in the organization to grant the necessary rights.

Besides needing the correct permission, it is also required that the organization has bought the rights to use the specific API endpoints. Not all products give access to all SCALAR APIs.

Audience

Audiences are used to include relevant permissions in the token. Each product is mapped to an audience, and when requesting a token, it is vital to request the correct audience so the appropriate permissions are included. You can find the list of audiences via: https://developers.zf-scalar.com/docs/audience

To support multiple audiences in a single token request, scopes are introduced. Scopes allow to request access to multiple features within a single audience. Include the required scopes in the token request, and the token is populated with features mapped to those scopes.Example: A developer wants to access features from user management and places APIs.Token Request: POST /v1/integrators/token/

{
  "clientId":"f2c9e0b3-b799-4c36-91b7-9bb6a791fa7b",
  "clientSecret":"12345abcdef",
  "audience":"API",
  "scope": ["UMAPI","PLAPI"]
}

How to get a token

To get a token call https://auth.api.eu1.scalar.zf.com/v1/integrators/token with Integrator Id, Secret, and Audience passed in the Request body.

{
  "clientId": "string",
  "clientSecret": "string",
  "audience": "string"
  "scope": ["scope1", "scope2"]
}

After successful API call, you will receive an access token as part of the API response. This token should be reused during the validity period of the token. The Response schema is shared below.

{
  "accessToken": "string",
  "expiresIn": 0,
  "tokenType": "string"
}

If audience is passed as "API" in the token request, the response will include the default features assigned to that integrator. If scopes are also provided, the token will include features specific to those scopes.

📘

Note: The access token will expire in every 1 hour. So once your token expires, you need to call the token endpoint again to get a new token