Field Guide
Client
The “Client” is the application requesting access to a protected resource on behalf of the Resource Owner (User). There are 2 types of Clients namely Confidential Clients and Public Clients.
Confidential Clients
Confidential clients are those who have the capability to keep the client_secret confidential. Mostly, these clients are only apps that run on a server under the developer’s control, with no access to the source code by the user.
A web application with a secure backend that uses the Authorization Code Flow is considered a Confidential application.
Public Clients
Public Clients are those who cannot hold credentials securely. Hence, public applications can only use grant types that do not require the use of their client secret.
A native application that uses the Authorization Code Flow with PKCE to be deployed on end-user machines is considered a Public application.
Grant
A grant is a protocol of acquiring an access token. Respective grant types are listed below under each Client. Refer to the GET authorize endpoint reference for more information.
Grant Types
Confidential applications can use grant types that require them to authenticate by specifying their client ID and client secret when calling the Token endpoint.
Public applications can only use grant types that do not require the use of their client secret.
Client ID
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 an alphanumeric string (e.g., 5zw90va0UuwMKTnPS5sLsdgZjDkVYXN7
), and it is passed as the value for the client_id
query parameter and JSON attribute.
Client Secret
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 an 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.
Access Token
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.
The expiry duration for access token is 60 minutes.
Refresh Token
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.
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 token endpoint returns a JSON object that includes a refresh token. For example:
{
"token_type": "Bearer",
"expires_in": 1800,
"refresh_token": "f2NWXxfnJOJMA1cW4k2zjFwmphf8vZjEUx3kmplFfn",
"access_token": "9WlQeEpOdVrAO9SOH8ab4m00Ngrd"
}
The expiry duration for refresh token is 15 days.