OAuth2 JWT Token Overview

🚧

Required auth method

Newly onboarding customers are required to implement the OAuth2 method for authentication. Please disregard ECDSA references.

Migrating from ECDSA to OAuth2 implementation guide here.

The JWT authentication scheme follows the conventional HTTP Bearer token scheme.

The Postman collection can be found here.

Auth Token Object

The returned Auth token from the /auth_token endpoint will have three attributes:

• token - string: an alpha-numeric that will be passed back for the base64-encoded token value in the Bearer token authorization header for subsequent API calls.
• expiration - int: an epoch timestamp designating the expiration timestamp in UTC.
• expiration_dt - string: a human-friendly date/time representation of the expiration timestamp; conforms to ISO 8601 date and time format in UTC.

NOTE: Use of an expired token will return a 401 response.

Auth Token Storage

You should cache or store the auth token object in your database.

There is no benefit to repeatedly requesting an Auth token

If you re-request a token for your app while your current token has more than 30 minutes left before it expires, the API will return the same token from the previous request. Only when your token has less than 30 minutes left will a new token be issued with a new full 8-hour window.

Auth Token requests will be rate-limited

Since rate limiting is in place on the /auth_token endpoint, you should implement caching the token on your end, and continue using the same token until its expiration time is less than 30 minutes. Requesting another token at this time will return a new token with a full 8-hour expiration window.

Requesting an Auth Token

Use the /auth_token endpoint to request or invalidate auth tokens.

When a Token Expires

When building a request, check the expiration time of the token and, if it's expired, first request a new token via /auth_token, cache the token returned, then build the HTTP Basic Authentication credentials string from the new auth_token.token value.

How to sign requests with a JWT Auth Token

After retrieving your token from calling /auth_token, you will include the below as part of the authorization header of all your API requests.

Authorization: Bearer [GENERATED 205 char JWT TOKEN HERE]

Authentication Failure Responses

There are various conditions relating to the use of an auth token which can produce an authentication error. Some of the returned error messages are deliberately vague to avoid exposing failure reasons in order not to encourage phishing.