Manage Tokens

Tokens are valid for 60 minutes, so you don't need a new one for each request. This page explains how to reuse tokens, how to track when they expire, and how to refresh them.

Reuse Your Token

A token can be used for any number of requests during its 60 minutes. Store it, and use it for every request, instead of requesting a new one each time. Reusing tokens is faster and puts less load on the service.

Track the Expiry

Each response includes expires_in, the number of seconds until the token expires. Add it to the time you received the token to work out its expiry time, and keep that time with the token.

• When you receive a token, record the time and the expires_in value.
• Before each request, check whether the token is close to expiring.
• If it is, request a new one first.

Token Caching

If you request a new token within 10 minutes of generating one, the API returns the same token. This keeps the load on the service low, and means you don't need to worry about accidentally flooding the token endpoint. It also means a request for a new token doesn't always return a new token with 60 minutes of life.

Refresh When the Token Expires

When a token expires, the API you call returns an error, 401 Unauthorized. Use it as the signal to request a fresh token, then retry the request that failed.

Build automatic refresh into your application.

1. Send the request with your current token.
2. If the response is 401, request a new token from the token endpoint.
3. Retry the original request with the new token.
4. If it still fails, check your credentials. See Troubleshooting.

Long-Running Jobs

Jobs that run for a long time, such as paging through a large universe or collecting results from a job, can outlast a token. Check the token before each request, and refresh it when needed. Don't wait for an error.

Keep Tokens Secure

• Store tokens and credentials securely, and don't put them in source code or logs.
• Don't send a token in a URL.
• Don't share your credentials. Request a token in the system that makes the calls.

Next Steps

• Get an Access Token explains how to request a token.
• Troubleshooting helps when a token request fails.