Skip to main content

Authorisation code flow

Introduction​

The ApprovalMax public API implements the OAuth 2.0 protocol for authorisation, which allows your application to access a user's account without needing a password. Your application requests specific permission scopes and, upon user approval, is granted an access token. This access token is then used to authorise subsequent API requests on behalf of the user, without exposing their password to your app. OAuth 2.0 provides a secure and standardised way to handle user authorisation in modern web applications.

1. Process of granting access to Organisations via the ApprovalMax Public API​

For granting access to Organisations, our API follows a specific process with the following steps:

  • Initiate user authorisation in your app: generate an URL with necessary parameters to direct the user to the ApprovalMax Public API Consent page
  • Proceed with a consent page: here, the user can select to which Organisations they want to grant access
  • Redirecting users back to your application with an authorisation code: redirect users back to your app's specified redirect URI with an authorisation code upon successful authorisation
  • Exchanging verification codes for access tokens: exchange the received authorisation code for an access token using the token endpoint with the appropriate parameters
  • Receiving your tokens: the token endpoint validates the request parameters and generates the tokens in the response upon successful validation

Upon successful completion of an OAuth flow you will be granted an access token that allows you to act on behalf of the user. You can then use this access token to determine which Organisation the user has connected to your app. Subsequently, you can make API calls by including both a valid access token and an authorised Organisation ID with each request.

Prerequisites for using the ApprovalMax Public API​

Before proceeding with the authorisation process for the ApprovalMax public API feature, certain prerequisites must be met:

  1. Accessing your data validation: for access to your data via the ApprovalMax public API, make sure your Organisation(-s) is/are under a Premium subscription, a trial, or an active All Features trial.
tip

Using ApprovalMax Public API explorer is not required for having Organisastions on a Premium subscription, a trial or an activated All Features trial.

  1. Creating an application in the My Applications: for access to the ApprovalMax public API feature it is mandatory to create an application in My Applications. This includes generating credentials that will be used for authentication purposes. Without the application and credentials, the API feature cannot be accessed. Please refer to the My Applications article to find out more about this.
  2. User roles: only an Account Owner, Account Manager or Organisation Administrator can grant access on the Consent page because it controls access to sensitive data. Without the appropriate user role, the system will deny access to the API feature.
info

Ensure that these prerequisites are met before proceeding with the API feature to avoid any disruptions or issues during the authorisation process.

2. Initiate the authorisation process​

To initiate the authorisation process you must create an URL with the required parameters that will redirect the user to the ApprovalMax system for authorisation. The URL must be structured in the following format:

GET https://identity.approvalmax.com/connect/authorize?
  response_type=code&
  client_id=CLIENT_ID&
  scope=SCOPES&
  redirect_uri=YOUR_REDIRECT_URI

The following values should be added as URL parameters:

  • response_type=code specifies that the server should return an authorisation code
  • client_id identifies the client application making the request
  • scope specifies the permissions or scopes requested by the client
  • redirect_uri specifies the URI to which the server should redirect after authorisation
  • state is a random value used to maintain state and prevent CSRF attacks

Redirect URIs​

All redirect URIs must be HTTPS. Custom URL Schemes are not supported.

Scopes​

The scope parameter is used to specify a space-separated list of OAuth scopes that determine the data your application can access. So far, the ApprovalMax Public API requires the following scopes:

  • https://www.approvalmax.com/scopes/public_api/write to enable the creation and modification of requests; it includes permissions to create, edit and submit requests
  • https://www.approvalmax.com/scopes/public_api/read to allow the retrieval of data from the API; intended for read-only access to the data
  • offline_access needs to be specified while initiating an authentication request through the endpoint for obtaining a refresh token
important

The https://www.approvalmax.com/scopes/public_api scope is supported for tokens that were generated previously but is no longer available for new tokens.

State​

The state parameter in OAuth 2.0 is used to maintain state information between the authorisation request and the authorisation response. It is typically used as a security measure to prevent cross-site request forgery (CSRF) attacks. While there are no strict specifications or standardised requirements for the state parameter in OAuth 2.0, there are some general considerations and best practices that should be followed:

  • Length: aim for a state parameter length of 16 to 32 characters to ensure compatibility with different systems and prevent issues with URL length limitations
  • Unpredictability: generate the state parameter using a cryptographically secure random number or string generation method with a high level of unpredictability
  • Encoding: properly URL-encode the state parameter to comply with the authorisation server's requirements
  • Confidentiality: avoid including any sensitive or confidential information in the state parameter
  • Verification and validation: implement robust verification and validation mechanisms to ensure the integrity of the state parameter
  • Lifetime and expiration: configure a short lifetime and expiration time for the state parameter to prevent potential misuse
  • Persistence and storage: store state values securely and delete them promptly after they are no longer needed to protect user privacy and prevent security risks

3. Grant access to Organisations via the Consent page​

As part of the authorisation flow – when the authorisation process is initiated – the Organisation Administrator, Account Owner or Manager is redirected to the Consent page to manually select the Organisation(s) they want to grant access to. This page contains a list of Organisations of which the person is the owner.

warning

Only Account Owners, Account Managers and Organisation Administrators are shown this list, and only they can authorise access to these organisations.

Choose organisations you want to grant access to and confirm

Once access has been granted to the selected Organisations, the Account Owner / Account Manager / Organisation Administrator will be redirected to the URL specified in the application in My Applications.

4. Redirecting users back to your application with an authorisation code​

When users authorise your app, ApprovalMax Public API will redirect them back to the redirect_uri that you specified. The redirection will include the following parameters:

  • code is a temporary code that can only be exchanged once and expires 5 minutes after it was issued
  • state values should match, otherwise it may indicate that the request was created by a third party and you should terminate the process

If any errors occur, or the user denies the request, the ApprovalMax Public API will redirect back to your redirect_uri with an "error" response.

5. Exchanging a verification code for an access token​

After receiving the verification code from the user, you can exchange it for an access token. Using the offline_access scope, you will receive a refresh token. To perform this exchange, you need to make a POST request to the token endpoint:

POST https://identity.approvalmax.com/connect/token

The request body should include the following parameters:

  • grant_type=authorization_code to specify the grant type as authorisation_code to indicate the type of token request being made
  • code is the authorisation code that you received in the callback from the authorisation server after the user has granted permission
  • redirect_uri is the same redirect URI that was used when initially requesting the authorisation code; this is used to verify that the authorisation code was issued for the same redirect URI
  • clientId is the client app key from your application created in My Applications
  • clientSecret is the app secret key from your application created in My Applications
POST https://identity.approvalmax.com/connect/token
Authorization: "Basic + base64encode(client_id + ":" + client_secret)"
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&
code=CODE&
redirect_uri=YOUR_REDIRECT_URI&
client_id=client_id&
client_secret=client_secret

6. Receiving your tokens​

The token endpoint validates the request parameters, including the expiration of the code and the matching client ID. If the validation is successful, the endpoint generates and returns the tokens in the response, which may include the following parameters:

  • access_token is used to authenticate API calls on behalf of the user
  • expires_in 3600
  • token_type is bearer
  • refresh_token is the token used to refresh the access token once it has expired; it is only returned if the offline_access scope is requested
"access_token":"eyJhbGciOiJQUzI1NiIsImtpZCI6ImJiYTUzOWViOTVkNDQzNWE5NTUwNmI4NTdlYWNmZjhlIiwidHlwIjoiYXQrand0In0.eyJuYmYiOjE2ODIzNDQwMTMsImV4cCI6MTY4MjM0NzYxMywiaXNzIjoiaHR0cHM6Ly9pZGVu
dGl0eWRldjA0LmFwcHJvdmFsbWF4LmNvbSIsImNsaWVudF9pZCI6IjMzOENENUUwQUJBNzQ0REI5MTE4MzhGOUY5QjA5Q0ZEIiwic3ViIjoiOTI1ODE4MDQtZjIwMi00YTg3LTkwYjEtYTRjOTY3N2I5MTQ2IiwiYXV0aF90aW1lIjoxNjgyMzMy
ODcyLCJpZHAiOiJBTVJlbW90ZSIsImh0dHBzOi8vd3d3LmFwcHJvdmFsbWF4LmNvbS9jb25uZWN0aW9uIjoiNGEyNTQxMDQtYjU4ZC00ZjJhLTgwNWEtNTk5ZWE4MTg0NmI5IiwianRpIjoiQjJBNEU2QjRDMkQyODk2Qjc2NUY1QTM2RUY5NzYy
MzQiLCJzaWQiOiIwRTA1OTExNTUzQTBCNUEyQTYwNUFEQjBBMDlFOUYyRCIsImlhdCI6MTY4MjM0MzcxOCwic2NvcGUiOlsiaHR0cHM6Ly93d3cuYXBwcm92YWxtYXguY29tL3Njb3Blcy9wdWJsaWNfYXBpIiwib2ZmbGluZV9hY2Nlc3MiXSwi
YW1yIjpbImV4dGVybmFsIl19.zkoFJyfbCsVEj6HKumrVoRCkhCQ6bZCi08EwpKtpaDCg_4KX7KJZnEgc7guSdmw4pLjiD2n_z7OcI6-EvHxX5hsum0pvmcUGEJMI1nHGT8XFggeAgptQaGr2wfF7NXc6ozTpY5YEBSMhwvTGmIDr_PGcdpc7Yp7
ITtkJVEAUtUMlHgkRdVlhVV4K1_lK8DSD1E3pT-_jjdkG99BGMGFMFOj7we3Ry-iacg3cZqgpzyY0aY7eLIIlPhNSOLVkVDN7kFSd1ILPY0IA-B5c2GvSYoSYQy1AjI0ePaylxpjALjZOiF7M-hL1rCuY-UloNuFstr3AkRsyNZQOpKOVYMoA8w"
,
"expires_in":3600,
"token_type":"Bearer",
"refresh_token":"C2495E877E3074027C0D232761D01B084FB264B3211588FA8932C8C01129B639",
"scope":"https://www.approvalmax.com/scopes/public_api offline_access"

Token expiry​

When you receive a token, it will have an associated expiry time after which it will no longer be valid. It's important to keep track of token expiry times to ensure that you request new tokens before they expire. Both access tokens and refresh tokens can be exchanged prior to expiry. Here are the token expiry times:

  • access_token: 1 hour
  • refresh_token: 30 days

Access token​

The access token is a JSON Web Token (JWT) that can be decoded to obtain a JSON object containing valuable information about the user and the authentication process. To decode your token, please, visit JWT.IO.

{
    "nbf": 1680885008,
    "exp": 1680888608,
    "iss": "https://identity.approvalmax.com",
    "client_id": "8A59498C02D54104B7295D1CA08EA586",
    "sub": "92581804-f202-4a87-90b1-a4c9677b9146",
    "auth_time": 1680869179,
    "idp": "AMRemote",
    "https://www.approvalmax.com/connection": "e018ad8d-7875-4f55-a17e-db5dec8dce25",
    "jti": "DD4A003D5F1B93E10B17E5D9EFCD9F3B",
    "sid": "A1C021867AA6360DC73B7A39878C444D",
    "iat": 1680880234,
    "scope": ["https://www.approvalmax.com/scopes/public_api", "openid", "offline_access"],
    "amr": ["external"]
}

7. Verify authorised Organisations with access permissions​

To determine which Organisations the Account Owner, Account Manager or Organisation Administrator has authorised, you can make a call to the /companies endpoint and provide a token you received. The response will be a list of the Organisation UUIDs to which access was granted. To retrieve the connections that were authorised in the current authentication flow, you have to visit the Connections List page on the ApprovalMax Main Application page.

info

If you wish to revoke access to a particular Organisation through the Public API, or add a new Organisation to the list of accessible entities, you will need to create a new connection by initiating the authorisation flow again. This is necessary to ensure the security and integrity of the sensitive data managed by ApprovalMax.

Disable & remove connections​

You can delete or remove a connection to revoke access to your data via the ApprovalMax Public API from the Connections List page on the ApprovalMax Main Application page. To delete a connection, the Account Owner, Account Manager or Organisation Administrator removes the connection so that it revokes any associated access tokens and refresh tokens.

warning

Please note: Only an Account Owner, Account Manager and Organisation Administrator can do this, and deleted connections cannot be restored. It would require the user to reauthorise the connection if they wanted to use your application again. The disabling process also involves the Account Owner, Account Manager and Organisation Administrator but can always be available to change a connection status.

8. Call the API​

tip

Try the ApprovalMax Public API endpoints here.

When making API calls, you must include the following headers in your request to ensure successful communication with the API:

  • Authorization header to include the access token obtained during the OAuth flow as a bearer token; the format of the header should be "Bearer + access_token"
  • Accept header to specify the type of response you expect from the API, like "application/json" for JSON response
GET https://public-api.approvalmax.com/api/v1/companies
Authorization: "Bearer + access_token"
Content-Type: application/json

Make sure to include these headers in your API requests to authenticate and communicate with the API correctly.

Access and refresh tokens​

An access token has an expiry time of 1 hour. Your application can automatically refresh an access token using a refresh token without user interaction. A refresh token is obtained by requesting the offline_access scope during the initial user authorisation.

warning

Your application must only request a refresh token if it is necessary and if it can be stored securely, for instance, in the keychain of the operating system.

To refresh the access token, you need to make a POST request to the token endpoint:

POST https://identity.approvalmax.com/connect/token

When refreshing an access token using a refresh token, the request body must include:

  • grant_type=refresh_token
  • refresh_token=YOURREFRESHTOKEN
  • clientId is the client app key from your application created in My Applications
  • clientSecret is the app secret key from your application created in My Applications

The grant_type parameter should be set to refresh_token to indicate that you are refreshing an access token. The refresh_token parameter should contain the refresh token obtained during the initial authorisation flow. Use these parameters in the request body when making a refresh token request to obtain a new access token without user interaction.

POST https://identity.approvalmax.com/connect/token
Authorization: "Bearer + access_token"
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token
&refresh_token=YOUR_REFRESH_TOKEN
&client_id=CLIENT_ID
&client_secret=CLIENT_SECRET

When refreshing an access token using a refresh token, the response will contain a new access token and refresh token. Both tokens must be saved by your application in order to maintain API access. If, for any reason, your application does not receive the response or fails to save the new tokens, you can retry using your existing refresh token for a grace period of 1 hour. After an hour, your previous refresh token will expire, and the user will need to reauthorise your API application in order to generate a new refresh token. It is important to handle this scenario correctly to ensure uninterrupted access to the API.

tip

You can decode your token here.

Rate limiting​

Rate limiting is a method used to control the amount of incoming requests to our API within a specified timeframe.

warning

The Public API enforces a rate limit of 1000 requests per minute. This limit is applied based on the combination of ClientId and CompanyId.

When an application reaches the limit, an error with the code 429 is returned along with the following message: Too many requests. Please try again after N second(s).

Pagination​

Pagination is a technique used in API responses to break down a large set of data into smaller, more manageable chunks or pages. This allows to retrieve and display data incrementally rather than all at once, improving efficiency and reducing the burden on both the server and the client.

The ApprovalMax Public API uses limit and continuationToken as parameters for pagination.

Adding a limit to a request determines how many items are to be on each page, and the server responds with a continuationToken indicating where to start fetching the next set of items. The combination of continuationToken and limit allows to navigate through a larger dataset in manageable chunks.

The maximum Limit is 100.

Additional Resources​

To further assist with implementing the authorisation code flow in your application, we provide the following additional resources:

  • Our Postman Tutorial demonstrates the authorisation code flow in action
  • In My Applications you will find the information about application creation that showcases the registration flow
  • Our Connections list guide explains how to manage your connections

These resources can serve as valuable references and guides for understanding and implementing the authorisation code flow in your application. They will help you to enhance the security of your authentication and authorisation processes.