Developer Documentation
Toggle Dark/Light/Auto mode Toggle Dark/Light/Auto mode Toggle Dark/Light/Auto mode Back to homepage

Get a Bearer Token

Let’s explain how our Bearer Token Authentication works. First, you make a POST request to the REST API login endpoint. If the authentication process is successful, the API will create a token for you that represents your authentication session. You must pass this token to us in subsequent API requests instead of your username and password.

The authentication session’s permissions will depend on the permissions associated with the username that you used to create the session. It will also be associated with the account that the user is under. Bearer tokens are only associated with a single account at any time.

Make a POST request to the login endpoint to get a token

Request Paramaters
Parameter Type Usage Description
username string Required The username to authenticate against
password string Required The username’s password
account_id integer Optional If the user has access to more than one account, specify the account id to be authenticated against here. You can alternatively perform a separate masquerade operation afterwards.
Response Body
   "success": true,
   "guid": "71067212-8141-4887-b48e-ccabcfb07196",
   "token": "c04c7ff7-5fa1-48fb-aa2a-bcf97a6b8a79",
   "tokenExpiration": "2018-04-01T21:39:12+00:00",
   "tokenLifetime": 3600,
   "refreshToken": "dff78899-ed3b-4965-8f44-474ac2bf7354",
   "refreshTokenExpiration": "2018-04-30T21:39:12+00:00",

Pass the Bearer Token on Subsequent REST API Calls

Now that you have a valid token that was returned to you in the token variable in the JSON response, you must add a special header for every subsequent request to the REST API. Inside of that header will contain the word “Bearer” as well as the value of the token. Often, a HTTP client library will support Bearer tokens, and it will add this header for you on subsequent requests for you per your configuration.

Authentication: Bearer c04c7ff7-5fa1-48fb-aa2a-bcf97a6b8a79

Don’t Forget About the Refresh Token!

Your bearer token is short lived. It will expire according to the value in tokenExpiration, whereby it will no longer be considered valid. Any attempt to use an expired bearer token will result in a 401 or 403 response. When you are ready to get a new bearer token, you must make a separate API call to refresh your auth session, and you must pass the refreshToken value to this endpoint.