About Authentication API

This endpoint issues access tokens that are used to authenticate requests to APIs that support token-based authentication.

🚧

Important

Currently, token-based authentication is required for the Async Events API and the Promotion Engine API. Additional APIs may adopt this authentication method in the future.

The authentication token endpoint enables machine-to-machine (M2M) communication by issuing short-lived access tokens to authorized client applications.

Instead of signing each request individually, clients authenticate once using their credentials, receive an access token, and use that token to authorize subsequent API requests.

Authentication model

The endpoint uses OAuth 2.0 with the Client Credentials grant type.

Client authentication is performed using a Client ID and Client Secret, which are issued per workspace and managed through the Management UI. These credentials identify the calling system and define the scopes it is allowed to request.

The token endpoint validates the provided credentials and requested scopes before issuing an access token.

Access tokens

When authentication is successful, the endpoint returns an access token along with metadata describing its usage:

• access_token - the token value used to authorize API requests
• token_type - always Bearer
• expires_in - the token lifetime in seconds
• scope - the scopes granted to the token

Access tokens must be included in API requests using the HTTP Authorization header:

Authorization: Bearer <access_token>

Access tokens are time-limited and expire automatically. A new token should be requested when the current one expires.

Scopes

Scopes define which APIs and operations the access token can be used for.

Supported scopes are:

• loyalty.async_events, which is required to access the Async Events API.
• promotions.all, which is required to access the Promotion Engine API.

When requesting a token, you must specify one or more scopes that match the permissions assigned to their credentials. If the requested scopes are invalid or not permitted, the token request will fail.

Error handling

If the token request cannot be fulfilled, the endpoint returns an appropriate HTTP status code along with a standardized OAuth 2.0 error response.

Common error scenarios include:

• missing or invalid request parameters
• invalid client credentials
• unsupported or unauthorized grant types
• invalid or malformed scopes