Token Introspection Endpoint

The introspection endpoint is used to validate whether a given access token is active for the user. This endpoint allows resource servers to verify the state and validity of an access token.

• Base URL: https://apx.didit.me
• Endpoint: /auth/v2/introspect
• Method: POST
• Content-Type: application/x-www-form-urlencoded
• Authentication: Basic Auth (Client ID and Client Secret)

Request

Headers

• Authorization: Basic {base64(client_id:client_secret)}
• Content-Type: application/x-www-form-urlencoded

Body Parameters

• token (required): The access token to validate.

Example Request

POST /auth/v2/introspect HTTP/1.1
Host: apx.didit.me
Authorization: Basic {base64(client_id:client_secret)}
Content-Type: application/x-www-form-urlencoded
 
token=eyJhbGciOiJSUzI1NiIsImtpZCI6Imp3a18yZmViZjY3MDc3N2UyY2NlNzY5YzUxOGM3MDNkNTNjMStN...

Response

Returns a JSON object containing information about the token's validity and associated metadata.

Example Response

{
    "active": true,
    "iss": "https://didit.me",
    "iat": 1678330528,
    "sub": "user-unique-identifier",
    "identifier": "alejandro@example.com",
    "identifier_type": "email",
    "claims": "email phone",
    "exp": 1678330528,
    "client_id": "app_550e829082fc558e112e0620c1c7a59"
}

Response Fields

• active: Boolean indicating whether the token is active.
• iss: The issuer of the token.
• iat: The time the token was issued.
• sub: The subject of the token (user identifier).
• identifier: The user's identifier (e.g., email address).
• identifier_type: The type of identifier (only email).
• claims: The claims associated with the token.
• exp: The expiration time of the token.
• client_id: The client ID associated with the token.

Error Responses

Errors are returned as JSON objects with an error field and optionally an error_description field.

Common Errors

• method_not_allowed: HTTP method is not allowed. Only POST may be used.
• invalid_content_type: The provided content type is invalid, only application/x-www-form-urlencoded is supported.
• required: A necessary attribute was not set. Required scopes are: token.
• unauthenticated: The authorization header is missing, please pass the Basic authorization token.
• invalid_token: The provided token was invalid or has expired.

Example Error Response

{
    "error": "invalid_token",
    "error_description": "The authorization token was invalid, and may be expired. Try generating a new token via /auth/token"
}

Code Example

const introspectToken = async (accessToken) => {
  const introspectUrl = 'https://apx.didit.me/auth/v2/introspect';
  const clientId = 'your_client_id';
  const clientSecret = 'your_client_secret';
 
  const params = new URLSearchParams();
  params.append('token', accessToken);
 
  try {
    const response = await fetch(introspectUrl, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/x-www-form-urlencoded',
        'Authorization': 'Basic ' + btoa(clientId + ':' + clientSecret)
      },
      body: params
    });
 
    if (!response.ok) {
      const errorData = await response.json();
      throw new Error(errorData.error_description || 'Token introspection failed');
    }
 
    const data = await response.json();
    return data;
  } catch (error) {
    console.error('Error introspecting token:', error);
    throw error;
  }
};