Login and authentication

The first step in any workflow using the REST API is to authenticate with the server. You issue a request to the login resource, providing a valid user name and password. The server responds with a string known as a bearer token. You then include that bearer token in an Authentication header with each subsequent REST API request. This methodology has the advantage that you only need to send user/password credentials one time, even if you intend to make hundreds of calls to the API.

Once it is included in a response from the login resource, the bearer token is valid for 18 hours. When designing a client application that uses the REST API, we recommend that you add logic to recognize an HTTP return code of 401 (authentication required) as a signal that your bearer token has expired and that you need to obtain a new one.

The REST API server maintains a user context cache for each bearer token instance. This cache is used to remember information about each authenticated user. This cache includes the following:

  • User name
  • Access permissions
  • Customer account ID
  • Query parameter values from the last request

The REST API issues unique bearer tokens for each login request, even if the requests use the same user/password credentials. This behavior allows the same user to use the REST API from multiple devices (for example, a desktop computer and a tablet). Each one of these user contexts will have its own user context cache.

Note

The service limits enforced by the server are calculated across all bearer tokens and user IDs for a given customer account.

Once your client software has obtained a bearer token string, you supply that token to all subsequent REST API requests in an Authentication header, which should look similar to the following:

Authentication: bearer bac389c4-cac3-434e-bcb7-11bc60bfaee5

This header must be present in all REST API requests (other than a login request). The bearer keyword is required, followed by a space and your bearer token string.