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.
    The scope is supported for previously generated tokens but no more for new ones.

  • https://www.approvalmax.com/scopes/public_api/write . The scope that allows to create requests (create, edit, submit).

  • https://www.approvalmax.com/scopes/public_api/read. The scope that allows to retrieve 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 ...

    • 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 grant access to an Organisation via the ApprovalMax Public API

      This is how you grant access to an Organisation via the ApprovalMax API: 1. Initiate a user authorisation: generate an URL with the necessary parameters to direct the Account Owner / Account Manager / Organisation Administrator to the ApprovalMax ...

    • 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, include the following headers in your requests to authenticate and communicate with the API correctly: ...

    • Public API Guide

      Our Public API Guide is available on our website, please follow this link to find it: ApprovalMax – Public API Guide