API Authentication

< All Topics

Overview

BLAM API uses a JWT bearer token authorisation model.  BLAM comes pre-configured with Basic Authentication for issuing bearer and refresh tokens by authenticating with a valid username and password.  The bearer token then provides the authorisation to access the API endpoints the user has the corresponding permissions for.  All bearer tokens automatically expire 5 minutes after being issued.  A new bearer token can be obtained either by using the refresh token or re-authenticating using the same username and password.

Basic Authentication

Basic authentication uses the inbuilt authentication scheme defined in the HTTP protocol.  The HTTP client must send a GET request to the BLAM API at /api/users/authorisation with the Authorization header that starts with the keyword Basic followed by a space and a base64-encoded string of username:password.  If your BLAM is multi-tenanted, the BLAM API also accepts an additional parameter for selecting the correct OrganisationId to authenticate with.

Single-tenant Deployment
curl -H "Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=" https://yourblam.bluelucy.com/api/users/authorisation
Multi-tenant Deployment
curl -H "Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=" https://yourblam.bluelucy.com/api/users/authorisation?OrganisationId=1

The BLAM API response with a JSON object containing the bearer and refresh tokens and their respective expiry dates.  The returned bearer token must be used when attempting to access the BLAM API.

Example response
{
"bearerToken": "eyJhbGci...",
"bearerTokenExpirationDate": "2020-07-17T10:51:44.762569Z",
"refreshToken": "lPGaIgV...",
"refreshTokenExpirationDate": "2020-07-18T10:46:44.7637827Z"
}

To use the token to BLAM API authorisation, add the bearer token to the Authorization header when making a request:

Example request
curl -H "Authorization: Bearer eyJhbGci..." https://yourblam.bluelucy.com/api/assets

Refresh Token

BLAM API JWT bearer tokens automatically expire after 5 minutes.  One method to obtain a new token is to use the refresh token which is issued at authentication.  The refresh token needs to be sent as a parameter in a GET request to the BLAM API /api/users/token endpoint along with the OrganisationId parameter for the correct organisation.  The default OrganisationId for single-tenant BLAM’s is 1.

curl "https://yourblam.bluelucy.com/api/users/token?RefreshToken=Vw4rR%2FG%2BPVRc3JzPGLEI4&OrganisationId=1"
Developer Tip: Ensure the refresh token is correctly URL encoded before calling the BLAM API or it will fail validation.