How to initiate an authorisation process

How to initiate an authorisation process

To initiate the authorisation process, you need to create a URL with the necessary parameters that will redirect the user to the ApprovalMax system for authorisation.

When incorporating values that should be added as parameters into the URL, the result should resemble the following format:
  1. https://identity.approvalmax.com/connect/authorize
  2. ?response_type=code
  3. &client_id=CLIENT_ID
  4. &scope=https%3A%2F%2F www.approvalmax.com%2Fscopes%2Fpublic_api%20offline_access
  5. &redirect_uri=YOUR_REDIRECT_URI
  6. &state=RANDOM_VALUE

Make sure to replace your_client_id, requested_scopes, your_redirect_uri, and random_state_value with the appropriate values specific to your application.
The following values should be added as parameters to the URL:

  • response_type=code : specifies that the server should return an authorisation code as the response.

  • client_id : used to identify the client application making the request. It ensures that the correct client is authorised to access the requested resources.

  • scope : used to define the permissions or scopes requested by the client. It specifies the level of access the client application is requesting.

  • redirect_uri : specifies the URI to which the server should redirect the user after the authorisation process is completed. This URI should be pre-configured and handled appropriately in your application.

  • state :   a random value to maintain state and prevent Cross-Site Request Forgery (CSRF) attacks. It helps ensure the integrity of the authorisation process.


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 . The scope that allows retrieving data

  • Offline_access. In order to obtain a refresh token, it is necessary to specify the offline_access scope while initiating an authentication request through the endpoint

State

The "state" parameter in OAuth 2.0 is used to maintain state information between the authorisation request and the authorisation response, and 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.




    • Related Articles

    • Prerequisites for using the Public API

      Before proceeding with the authorisation process for the ApprovalMax Public API feature, there are certain prerequisites that need to be met. These include: 1. Granting access to the Developer Portal: in order to access the Developer Portal and ...

    • How to grant access to an Organisation in the ApprovalMax Public API

      The process of granting access to an Organisation consists of the following steps: 1. Initiate user authorisation: generate an URL with the necessary parameters. This URL will direct account owners/ account managers to the ApprovalMax Public API ...

    • Redirecting users back to your application with an authorisation code

      When users authorise your app and interact with the ApprovalMax Public API, the API will redirect them back to the redirect_uri that you have specified. During this redirection process, certain parameters will be included in the URL: code: represents ...

    • How to call the API?

      Please refer to the Swagger page or the list of available endpoints to find endpoints and their data models. To successfully make API calls, ensure that you include the following headers in your requests: Authorisation header: this is crucial for ...

    • How to exchange an authorisation code for an access token

      Once you have obtained the authorisation code from the user, you can proceed to exchange it for an access token. When making this exchange, it is recommended to request the "offline_access" scope, which allows you to receive a refresh token in ...