Authentication

To interact with the Identity Verification API, you need to authenticate using an access_token. This token is required for all API requests to ensure secure access.

Base URL: https://apx.didit.me
Endpoint: /auth/v2/token/
Method: POST
Authentication: Basic Authentication

⚠️

The authentication endpoint uses a different base URL than the verification session endpoints. Ensure you use the correct URLs to avoid connectivity issues.

Request

Follow these steps to obtain an authentication token programmatically:

Step 1: Register Your Application

First, you need to register your application with the Identity Verification service as explained in the Quick Start Guide. This involves obtaining a Client ID and Client secret, which will be used to authenticate your application.

⚠️

Keep your Client ID and Client Secret secure. Never share the Client Secret credentials or expose them in client-side code.

Step 2: Prepare Authentication Parameters

To retrieve the encodedCredentials, follow these steps:

Combine Credentials: Concatenate your Client ID and Client Secret with a colon (:) in between.
Base64 Encode: Encode the combined string using Base64. This encoded string will be used as encodedCredentials.

Include the encodedCredentials in the Authorization header of your request and use the grant type client_credentials.

Parameter	Type	Required?	Description	Example Value
`grant_type`	`string`	Yes	The OAuth 2.0 grant type to use. Must be set to `client_credentials`.	`"client_credentials"`

Step 3: Send the Request

Make a POST request to /auth/v2/token/ with the prepared parameters.

Example Request

POST /auth/v2/token/ HTTP/1.1
Host: apx.didit.me
Content-Type: application/x-www-form-urlencoded
Authorization: Basic ${encodedCredentials}
 
grant_type=client_credentials

Response

Upon successful authentication, the server responds with a JSON object containing the access token and related information.

Example Response

{
  "iss": "https://didit.me",
  "iat": 1617220000,
  "sub": "your-application-uuid",
  "client_id": "your-client-id",
  "organization_id": "your-organization-id",
  "expires_in": 86400,
  "exp": 1618084000,
  "access_token": "your-client-access-token"
}

Response Fields

Field	Type	Description
`iss`	`string`	Issuer of the token.
`iat`	`number`	Timestamp when the token was issued (Unix timestamp).
`sub`	`string`	Subject of the token (your application UUID).
`client_id`	`string`	Your application's client ID.
`organization_id`	`string`	Your organization's ID in the system.
`expires_in`	`number`	Token validity period in seconds (typically 24 hours or 86400 seconds).
`exp`	`number`	Timestamp when the token will expire (Unix timestamp).
`access_token`	`string`	The access token to use in subsequent API requests.

Error Handling

Status Code	Error	Description
`401`	Unauthorized	Invalid client credentials or incorrect encoding format.
`400`	Bad Request	Missing or invalid grant_type parameter.

Example Error Response

{
  "detail": "Invalid authorization header"
}

Token Usage

The access_token is valid for 24 hours (86400 seconds)
Include it in the Authorization header as a Bearer token for all API requests
Store the token securely and refresh it before expiration

For production systems, implement token caching to avoid unnecessary authentication requests.

Code Examples

const fetchClientToken = async () => {
  const url = 'https://apx.didit.me/auth/v2/token/';
  const clientID = process.env.DIDIT_CLIENT_ID;
  const clientSecret = process.env.DIDIT_CLIENT_SECRET;
 
  const encodedCredentials = Buffer.from(
    `${clientID}:${clientSecret}`,
  ).toString('base64');
 
  const params = new URLSearchParams();
  params.append('grant_type', 'client_credentials');
 
  try {
    const response = await fetch(url, {
      method: 'POST',
      headers: {
        Authorization: `Basic ${encodedCredentials}`,
        'Content-Type': 'application/x-www-form-urlencoded',
      },
      body: params,
    });
 
    const data = await response.json();
 
    if (response.ok) {
      return data;
    } else {
      console.error('Error fetching client token:', data.error_description || data.message);
      return null;
    }
  } catch (error) {
    console.error('Network error:', error);
    return null;
  }
};

Workflows Create Session