GuidesAPI ReferenceApplixure Web UI

Client Credentials Grant

Suggest Edits

Overview

Client Credentials Grant is meant for obtaining access token using single-step process of:

  1. Use Applixure API credential keypair as authentication using Token endpoint to receive valid access token

Typically you would want to use this grant if you need to access APIs non-interactively on software running on background or independently and with fixed credentials.
For interactive purposes and/or using Applixure user account credentials to obtain access to an API, you should use Authorization Code Grant flow instead.

Flow description

Getting access token

To receive access token, you will need to send application/x-www-form-urlencoded encoded HTTP request in UTF-8 character set to the token endpoint with following parameters:

ParameterExplanationIs mandatory?
grant_typeMust be set to: client_credentialsYes
scopeRequested scopes (depending on API being used).Yes, if no default scopes are defined for client application registration.

No, if default scopes are defined for client application registration - in that case pre-defined scopes will be used for request.

📘

An example of token endpoint payload

grant_type=client_credentials&scope=account-all%3Aread+account-data%3Amanage

To authenticate the request with your API credential keypair, you have two alternatives:

  1. Encoding Key ID and Key Secret as username and password -parts for HTTP Basic Authentication (authentication information in the HTTP request header)
  2. Adding Key ID and Key Secret as parameters to application/x-www-form-urlencoded encoded request body as additional client_id and client_secret parameters (authentication information in the HTTP request body)

🚧

HTTP request body authentication NOT RECOMMENDED

As per RFC 6749 Section 2.3.1, authentication using HTTP request body is not recommended and HTTP request header -method should always be favoured instead.

AAS supports both methods but Applixure always recommend using headers for authentication.

Successful call result

If token endpoint call is successful, you will receive JSON formatted payload back with following properties available:

PropertyData typeExplanation
access_tokenstringAccess token.

This is a token to use subsequently for authorizing requests to Applixure APIs.
expires_inintegerValidity time of the access token in seconds from the time of issuance.

Always set to 3600 i.e. 1 hour.

Caller is responsible for tracking lifetime of access tokens it has received for longer time usage and if necessary, refresh it using refresh_token (if present).
scopestringA space-delimited list of scopes that has been granted for access token.

Please note that depending on the privileges and permissions of the user account that was used to authenticate in phase 1 of the flow, granted scopes may be a subset of the scopes originally requested!
token_typestringAAS always returns tokens of type bearer

📘

An example of success JSON payload

{ "access_token": "2bCL1o2gTwFrsMaSFBK1FbusqfdDUR5J7WyDcci8BkxY4zzQZ7S...", "token_type": "bearer", "expires_in": 3600, "scope": "account-all:read account-data:manage" }

📘

Refresh token not supported

Applixure AAS does not provide refresh tokens in Client Credential Grant responses, as new valid access tokens can be obtained after expiration of the existing one using the same Client Credential Grant flow as with the original authorization.

Error call result

Possible HTTP error response codes returned are:

HTTP Error CodeCondition
400 - Bad RequestNormal error condition when request could not be processed by the token endpoint as per RFC 6749 Section 5.2.

Please inspect returned JSON response body for a reason for call failure.
500 - Internal Server ErrorTemporary error - retry after a while is recommended.

If condition persist, please be in contact with Applixure support for further assistance.
503 - Service UnavailableAAS is temporarily offline - retry after short while is recommended.

Updated about 1 year ago