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://asset-management.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 a set of 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 privileged user in the customer organization to grant the necessary rights.

In addition to having the correct permissions, it is also required that the organization has bought the access to use the specific API endpoints, as API availability depends on the purchased product.

How to request a token

To get a token, you need 3 pieces of information:

• clientId
• secret
• audience

clientId and secret are provided by the customer, more information can be found via Integrator management - Help Center

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: Audience list

There are 3 different ways to specify an audience in your token request.

Token per module

You can request a token per module by specifying the specific audience in the request.

This token is valid for 1 hour and it is possible to request this token 3 times per hour per audience.

This option provides the highest level of security by limiting each token to a single module with a short lifespan. It minimizes the impact of token leakage but requires more complex token management and frequent renewals.

{
  "clientId": "string",
  "clientSecret": "string",
  "audience": "AMAPI"
}

Token for all accessible modules

You can request a token with the general API audience which will grant you access to every module which is configured for your integrator.

This token is valid for 24 hours and it is possible to request this token 15 times per day.

This is the simplest option to implement, using one long-lived token with broad access. While convenient and low‑maintenance, it poses higher security risks due to its wide scope.

{
  "clientId": "string",
  "clientSecret": "string",
  "audience": "API"
}

Token with scopes

You can request a token with the general API audience including specific modules as a scope to only grant access to those specific modules.

This token is valid for 24 hours and it is possible to request this token 15 times per day.

This option strikes a balance by granting access only to specified modules while remaining valid for a full day. It offers improved security over a global token with moderate implementation complexity.

{
  "clientId": "string",
  "clientSecret": "string",
  "audience": "API",
  "scopes": ["AMAPI", "UMAPI"]
}

Token response

📘

Due to the limited number of tokens that can be generated within a given timeframe, we strongly advise beginning your implementation by storing the token.

After a 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.

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