Before you can make calls to any of Xandr's API services or reports, you must use your username and password to get an authorization token. The token remains active for 2 hours, during which you do not need to re-authenticate. Furthermore, there is a 24 hour hard expiry. When an API session reaches the 24 hour mark, regardless of when the most recent API call was made, that session will expire.
This page walks you through the authentication process.
For an explanation of the errors that you may encounter during and after authentication, see Error Messages.
Step 1. Create a JSON file including your username and password
Below, we have used the
cat command to show the output of the file.
Guidelines for creating your password
When creating your password, please create a complex password with the following:
- 10 or more characters
- 64 or fewer characters
- At least one capital letter (A–Z)
- At least one lowercase letter (a–z)
- At least one digit (0–9)
- At least one special character (such as #, $, ? %, &)
Step 2. POST the file to the authentication service
The request returns a token that remains valid for the 2 hours following your most recent call to the API. We suggest using "-b cookies -c cookies" in the POST request to store the token in a cookie.
Step 3. Use the token when making calls to API services and reports
In the example below, we call the Member Service and authenticate using the token stored in the cookie.
Alternately, if you didn't store the token in a cookie, you can put the token in the request header as
For added security, it's also possible to authenticate using JSON Web Tokens. See Token-Based API Authentication for more information.
After authenticating, your token remains valid for 2 hours. You do not need to re-authenticate within this time. If you do re-authenticate, please note the following limitation: The API permits you to authenticate successfully 10 times per 5-minute period. Any subsequent authentication attempts within those 5 minutes will result in an error.
It is best practice to listen for the
error_id in your call responses and re-authenticate only after receiving it.