Skip to content

Adaptix OAuth 2.0 Integration Guide (Authorization Code Flow)

This is a detailed guide for implementing an OAuth 2.0 Authorization Code Flow for integrating your application with Adaptix.

Step 1: Pre-Configuration (Adaptix & Your App)

Before writing any code, you must establish the necessary credentials and URLs in both systems.

Adaptix Setup

  1. Log in to your Adaptix instance.
  2. Go to Settings (gear icon) > Developers > APP Credentials.
  3. Create a new OAuth 2.0 credential.
  4. Crucially, set the Redirect URI to the exact URL on your application where Adaptix will send the user back after authorization. This is your Callback Endpoint. > Example: https://app.validify.ai/integrations/adaptix/callback
  5. Save, and copy the generated Client ID and Client Secret.

Your App Setup

  1. Store the Client ID and Client Secret securely.
  2. Define the Adaptix Base URL (e.g., https://instance.adptix.ai).

Step 2: Initiate Authorization (The Redirect)

This action is triggered when the user initiates the connection (e.g., clicks "Connect Adaptix"). Your application constructs and redirects the user's browser to the Adaptix authorization endpoint.

Action: Redirect the user's browser to the Adaptix Auth URL with the following query parameters:

Parameter Value Description
client_id (Your Client ID) Public key from Adaptix.
redirect_uri (Your Callback Endpoint) Must be URL-encoded and must match the URL registered in Adaptix (Step 1).
response_type code Specifies you are requesting an authorization code.
state (A unique, unguessable string) Used to prevent Cross-Site Request Forgery (CSRF). Generate this for each session and verify it in Step 3.

Example Adaptix Authorization URL Structure: https://instance.adaptix.ai/oauth/v2/authorize?client_id=YOUR_CLIENT_ID&redirect_uri=YOUR_URL_ENCODED_CALLBACK_ENDPOINT&response_type=code&state=UNIQUE_STATE_STRING

The user will log into Adaptix and see a consent screen asking to grant your application access.

Step 3: Handle the Callback (Retrieve Code)

After the user grants access, Adaptix redirects the browser back to the redirect_uri (your callback endpoint) with the authorization code and state appended as query parameters.

Action: Your callback endpoint receives a GET request.

  • Retrieve: Get the code and state values from the URL query.
  • Validate State: Compare the received state value with the unique value stored in the user's session (from Step 2). If they do not match, abort the process immediately to prevent CSRF attacks.
  • Store: Save the code value; it is temporary.

Step 4: Exchange Code for Tokens (Server-Side)

This step must be performed server-side to keep your Client Secret secure. Your server uses the temporary authorization code to request the final access token from Adaptix's token endpoint.

Action: Send a POST request to the Adaptix Token URL.

Parameter Value Description
Method POST
URL https://instance.adaptix.ai/oauth/v2/token Adaptix's token exchange endpoint.
Content-Type application/x-www-form-urlencoded Standard for this grant type.
grant_type authorization_code Specifies the type of exchange.
client_id (Your Client ID)
client_secret (Your Client Secret) Only used server-side.
redirect_uri (Your Callback Endpoint) Must be the exact (unencoded) URL used in Step 2.
code (The code received in Step 3) The temporary authorization code.

Expected Response (JSON):

Adaptix will respond with the tokens your app needs:

{
    "access_token": "YOUR_ACCESS_TOKEN",
    "expires_in": 3600,         // Time until token expires (e.g., 1 hour)
    "token_type": "Bearer",
    "scope": null,
    "refresh_token": "YOUR_REFRESH_TOKEN"
}

Step 5: Storage and Usage

  • Store: Securely save the access_token and refresh_token associated with the Adaptix instance and your user.

  • Use: To make API calls to Adaptix , you must include the access_token in the Authorization header of every request: 

Authorization: Bearer YOUR_ACCESS_TOKEN
  • Refresh: When the access_token expires, use the refresh_token to get a new access_token without requiring the user to log in again (This is a separate POST request to the /oauth/v2/token endpoint with grant_type=refresh_token).