Bearer Authentication
Bearer Authentication is the method used to authorize secure API requests using an access token. Once a valid access token is obtained, it must be included in the Authorization header of every API call to authenticate the request.
Authorization: Bearer <access_token>
This token proves the identity and permissions of the requestor, and is required for accessing any secured endpoints in the system. Ensure tokens are stored securely and are refreshed or re-requested as needed according to your environment’s expiration rules.
Retrieving an Access Token
Before making any authenticated API calls, you must first retrieve an access token from the platform’s token service. The access token request must include the appropriate sourceId, tenantId, userId, and pre-assigned key.
For API integrations, it’s common to automate this token retrieval process at the start of each session or as part of an application’s initialization routine.
For a full example of how to retrieve an access token programmatically, refer to:
Access Token Example
Example Payload
{
"header": {
"sourceId": "a1b2c3d4-e5f6-7890-abcd-1234567890ab",
"tenantId": "123e4567-e89b-12d3-a456-426614174000",
"userId": "987f6543-dcba-4321-fedc-0987654321fe"
},
"body": {
"key": "superSecureClientToken123!"
}
}Example Response
{
"accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkNsaW5pY2FsIEFjY2VzcyIsImlhdCI6MTY5MDAwMDAwMH0.4QlRgPz9JCPQaR50AVjJkS9OpXkPRCyzOP7fr31Rv8M"
}Access Token Field Definitions
The header object in the access token request follows the same structure used in other authenticated service calls across the platform. Each field—sourceId, tenantId, and userId—is defined according to standard header requirements.
The access token request consists of two sections or objects: a standard header and a body.
The
headerfollows the shared platform convention and containssourceId,tenantId, anduserId. These fields should be populated the same way as in other authenticated service calls.For detailed definitions, refer to the Header Definitions section.
The
bodycontains the api key required to request the token. Refer to Generating an API Key for details.