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.
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.