Authorization Code Grant


Authorization Code Grant is meant for obtaining access token using two-step process of:

  1. User interactively performs logon against Authentication Server at the Authorization endpoint, resulting Authorization Code upon successful logon
  2. Exchanging Authorization Code using Token endpoint into valid access token

Typically you would want to use this grant if you need to access APIs on behalf of some Applixure user account rather than in non-interactive machine-to-machine communication context. For non-interactive purposes, you should use Client Credentials Grant flow.


Authorization Code Grant vs. Authorization Code Grant with PKCE

Applixure recommends implementing Authorization Code Grant flow always with the PKCE extension for increased security.

Future revisions of Oauth2 standard may deprecate the use of Authorization Code Grants without the use of PKCE.

Flow description

Authentication with browser

In technical terms, first step requires opening up Internet browser for the user and navigating into Authorization endpoint URL with the following parameters in the URI:

URI parameterExplanationIs mandatory?
response_typeMust be set to: codeYes
client_idApplication ID you have obtained for your registered client application.Yes
redirect_uriURI that AAS uses to redirect browser in order to return result of the authentication and authorization operation to the caller.

This value must match to one of the pre-defined redirect URIs for client application - Authorization Server never calls any other URIs.

Must use HTTPS protocol or application specific protocol, except for localhost URIs for which HTTP is accepted.
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.
stateOpaque value used by the caller to maintain state/association between the call and getting the redirected response, that echoes this value as-is back.No, but strongly recommended to prevent cross-site request forgery.


An example of authorization endpoint URL

As this phase only requires Application ID for registered client application, it can be initiated from applications that are publicly distributed and running on untrusted devices.

User will then see the Applixure logon screen and has to enter valid user account credentials, optionally verify logon with with 2FA token and finally consent into allowing the client application to obtain requested permissions as defined by the scopes.


Consent on first use

Once user has consented for specific scopes for specific registered client application, AAS will no longer ask about consent for the same application and for the same scopes for that user account.

Depending on the result of authentication and authorization operation, AAS will finally call back (i.e. redirect the browser) into specified callback URI that the client application should listen to to continue forward with the flow.

As AAS will redirect using GET HTTP method, both success and error result is signalled through URI parameters for the callback URI and no request body is used for the purpose.

If authentication attempt resulted an error response, do not proceed to next phase but handle the error condition and/or notify the user appropriately.


An example of authorization code callback URL



Remember to check state!

If and when using state parameter, make sure to verify that your callback URI receives the same state parameter value back you originally generated for the request. If not, you should discard the response!

Getting access token

Next, using the authorization code received from the Authentication Server, you must exchange this code into valid access token using another endpoint.


Do NOT use for code running on untrusted client devices

This phase should NOT be run from untrusted client or device - such Javascript running in user's Internet browser or publicly available mobile or other applications - as retrieving token necessitates storing Client secret of your registered client application at the client side.

With both Application ID and Client secret, anyone can impersonate your registered client application and may lead to Applixure disabling such registration if misuse is detect!

As an alternative for such environment, you should use Authorization Code Grant variation using Proof Key for Code Exchange (PKCE).

For token exchange, 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: authorization_codeYes
codeAuthorization code that you received from the callback.Yes
redirect_uriOriginal redirect_uri value used in the first phase when performing authentication.Yes


An example of token endpoint payload


Additionally, you must authenticate your client application for the request. OAuth2 specification for Authorization Code Grant flow supports using unauthenticated clients, but Applixure Authentication Servers requires that normal Authorization Code Grant flow clients authenticate themselves, except in the case of Authorization Code Grant with PKCE flow.

Authenticating the client happens by two alternative ways:

  1. Encoding Application ID and Client secret as username and password -parts for HTTP Basic Authentication (authentication information in the HTTP request header)
  2. Adding Application ID and Client 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 client application 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).
refresh_tokenstringRefresh token (if issued).

This is a token to use to obtain a new access token when the lifetime validity of access token expires (see: expires_in).

Refresh tokens are valid for 90 days from issuance.
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, "refresh_token": "AXXtUZBWvfee7KSiSL98RwhYtNwEMhaswN7LkySYPXoUneYmi8mny4AzmtpRvs6dcK...", "scope": "environments:read users:manage" }

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.