Authentication

Authentication is a critical part of our APIs. It ensures that only authorized users and applications can access and interact with our platform. This guide explains how to authenticate securely with our APIs and gain authorized access to endpoints.

Authentication Technology

Our API uses industry-standard technologies to provide secure and reliable authentication.

OAuth 2.0

OAuth 2.0 is a widely adopted protocol for authorization and access delegation. It allows applications to access user data without exposing passwords. OAuth 2.0 provides a robust, token-based authentication framework.

When using OAuth 2.0 with our API:

Users or applications request an access token.
The access token is a JSON Web Token (JWT) used to authenticate API requests.

JSON Web Tokens (JWT)

JWTs are compact, URL-safe tokens that represent claims securely between two parties. Our APIs use JWTs for access tokens, ensuring the integrity and identity of the caller.

Access Tokens

The access tokens used are JSON Web Tokens (JWT). These tokens provide clients access to API endpoints for a limited time and are used to determine the identity of the caller. Tokens are signed by the OAuth2 service and verified by the API on every call to ensure the integrity of the caller. They are time-limited, reducing the risk of misuse.

Client Credentials Flow

The client credentials flow is used for machine-to-machine (M2M) applications, where the client application requests access tokens directly from the authorization server. You can use a set of specifically created credentials to authenticate your applications: a Client ID and a Secret. This flow is ideal for server-to-server interactions.

Before using this flow, you need to have access to our API and get credentials: Client ID and Client Secret.

📘
Tip: You can choose your own Client ID.
The Client Secret acts like your API key. It can be generated in the API Token field or provided by our connectivity team.

Acquiring an access token

To request an access token, create the authorization header for basic authentication. The headers must include the following parameters: the Authorization header, which is a Base 64-encoded string that contains the client ID and client secret key, and Content-Type header, which indicates the media type of a resource.

Header Parameter	Value
`Authorization`	`Authorization: Basic <base64 encoded client_id:client_secret>`
`Content-Type`	`application/x-www-form-urlencoded`

After setting up the headers, the next step is to send a POST request to the /oauth/v2/token endpoint with the following parameters encoded in application/x-www-form-urlencoded format:

Body Parameter	Value
`grant_type`	`client_credentials`

If credentials are valid, the server responds with HTTP 200 OK:

{
  "token_type": "Bearer",
  "expires_in": 3600,
  "access_token": "NgXCXRKc...Mz0Yjw="
}

key	Description
`access_token`	An access token that must be used in subsequent calls to the APIs.
`token_type`	The type of token: always `Bearer`
`expires_in`	The time (in seconds) for which the access token is valid

If credentials are invalid, you will receive HTTP 401 Unauthorized.

Use access token for API requests

To call an API endpoint, include the access token in the Authorization header

Header Parameter	Value
`Authorization`	`Bearer <access_token>`

If everything is done correctly, you should receive a response in the 2xx range, which means the request has been successfully processed.

If the API returns an error message with the status code 401 Unauthorized, check token validity or credentials. If you receive 403 Forbidden, check account permissions and access.