Field Guide

The “client ID” is essentially your app’s username and can be found in the My Apps section.

On other platforms, this is sometimes called “consumer key” or “API key”.

It is a 32-character alphanumeric string (e.g., 5zw90va0UuwMKTnPS5sLsdgZjDkVYXN7), and it is passed as the value for the client_id query parameter and JSON attribute.

The “client secret” is essentially your app’s password and can be found next to the client ID in the My Apps section.

On other platforms, this is sometimes called “consumer secret” or “API secret”.

It is a 16-character alphanumeric string (e.g., 7I6uN1rjneirxiMW), and it is passed as the value for the client_secret query parameter.

If you lose control of your credentials, you can regenerate your client secret.

In a three-legged authorization code grant type flow, an authorization code is passed through a code query parameter when the user is redirected back to the app via the callback URL. Anything returned this way is accessible to the end user and, in principle, any intermediate system (including spyware in a browser extension).

For this reason, returning an access token directly poses a security risk. But an authorization code on its own cannot be used to get an access token; the app has to supplement it with its client ID and secret in the POST gettoken endpoint. Because the end user (and any part of the app that runs in the web browser) does not have the client ID and secret, the access token is not exposed.

The authorization code is a 40-character string (e.g., wroM1vFA4E-Aj241-quh_LVjm7UldawnNgYEHQ8I).

An access token (sometimes just “token” or “bearer token”) is returned at the end of a successful authentication flow.

The token is used in subsequent API calls to APS. The platform keeps track of what resources the token is entitled to access and either allows or denies access at call time.

APS uses JSON Web Tokens (JWT), which are alphanumeric strings of variable length (including periods to spearate their different parts), and they are passed as the value for the access_token JSON attribute and token query parameter.

Tokens have a limited lifespan and expire after the number of seconds specified in the expires_in JSON attribute that is returned alongside the access_token attribute when it is first acquired.

In a two-legged context, the POST authenticate endpoint returns a JSON object that includes an access token. For example:

{
  "token_type": "Bearer",
  "expires_in": 1800,
  "access_token": "eyJhbGciOiJIUzI1NiIsImtpZCI6Imp3dF9zeW1tZXRyaWNfa2V5In0.eyJjbGllbnRfaWQiOiJ5b3VyX2NsaWVudF9pZCIsImV4cCI6MTQ4NzU2NzgwMSwic2NvcGUiOlsiZGF0YTpyZWFkIl0sImF1ZCI6Imh0dHBzOi8vYXV0b2Rlc2suY29tL2F1ZC9qd3RleHAzMCIsImp0aSI6InJZcEZZTURyemtMOWZ1ZFdKSVVlVkxucGNWT29BTDg0dFpKbXlmZ29ORW1MakF0YVVtWktRWU1lYUR2UGlnNGsifQ.r2DIhTXrcZcHDA7bOtwm97paC7QcOgC7_l_3mcxMvAc"
}

In a three-legged context, it would be very disruptive to require that an end user of your app be required to go through the authentication flow every time the access token expired. When your app obtains a three-legged token, it is also provided a refresh token, which can be used with the POST refreshtoken endpoint to get a new three-legged access token without involving the user by putting them through another authentication flow. (See the “Common Authentication and Authorization Flows” section on the API Basics page for more information.)

It is a 42-character alphanumeric strings (e.g., SDrclmgQSGyF79wjLqxQeEIjqELf0wE8aMym02PjRy), and it is passed as the value for the refresh_token query parameter and JSON attribute.

In a three-legged context, the POST gettoken endpoint returns a JSON object that includes a refresh token. For example:

{
  "token_type": "Bearer",
  "expires_in": 1800,
  "refresh_token": "f2NWXxfnJOJMA1cW4k2zjFwmphf8vZjEUx3kmplFfn",
  "access_token": "9WlQeEpOdVrAO9SOH8ab4m00Ngrd"
}