Token introspection API

Use token introspection to validate access tokens.

This endpoint implements token introspection according to RFC 7662 - OAuth 2.0 Token Introspection.

Endpoint:

POST /oauth/api/v2/token/introspect

Require scope

This endpoint requires authentication with valid API client credentials that use the onegini_api_token_introspection scope.

Request parameters

This endpoint accepts the following parameters, form-urlencoded in the request body:

Parameter	Required	Example value	Description
token	yes	24CAD1DA628B360B7EF85C30E423D0AB0FC0DCF8C7EB8CAD9640DBABE43910F9	The value of the access token
refresh_user_details	no	true	The properties of the `user_details` object from the user info endpoint are cached after the first request. Use this parameter to force fetching the user details again from the user info endpoint. Performance might decrease if you add this parameter to every request.

Custom attributes

Our implementation extends the introspection response object, which is described in paragraph 2.2 of the token introspection specification, with a number of custom parameters:

Attribute	Description
usage_count	[DEPRECATED] Since being deprecated, it's always equal to 0.
usage_limit	[DEPRECATED] Since being deprecated, it's always equal to 0.
user_details	List of details about the user. Depending on the configured user detail mappings in the identity provider, this array can differ in size.
amr	The Authentication Methods Reference (AMR) is a JSON array of strings that identify the authentication method that was used during authentication. The possible values are the OneWelcome Identity Platform token types: `DEFAULT`, `FINGER_PRINT`, `IMPLICIT`, or `CUSTOM_AUTHENTICATOR`.
app_identifier	The identifier of the mobile app is empty when the client is not an instance of a mobile app.
app_platform	The platform of the mobile app is empty when the client is not an instance of a mobile app.
app_version	The version of the mobile app is empty when the client is not an instance of a mobile app.
app_identifier	The identifier of the mobile app is empty when the client is not an instance of a mobile app.
app_platform	The platform of the mobile app is empty when the client is not an instance of a mobile app.
app_version	The version of the mobile app is empty when the client is not an instance of a mobile app.
group_permissions	[DEPRECATED] The stringified representation of the user's group memberships and permissions requires configuring the DABP API and setting the legacy group permissions.
urn:onegini.com:oidc:group_policies	The user's policies and group memberships requires configuring the DABP API.

Examples

Example token introspection request:

POST /oauth/api/v2/token/introspect HTTP/1.1
Host: onewelcome.example.com
Accept: application/json
Content-Type: application/x-www-form-urlencoded
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW

token=24CAD1DA628B360B7EF85C30E423D0AB0FC0DCF8C7EB8CAD9640DBABE43910F9

Example token introspection response for a valid access token:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "active": true,
  "scope": "read",
  "client_id": "D4CFB02DA92C083934665000199A09DE793C97F94C9714DE3D38C3E5D2985494",
  "token_type": "bearer",
  "exp": 1686258829,
  "iat": 1504011352,
  "nbf": 1504011352,
  "sub": "TestClientUserId",
  "app_identifier": "TestAppId",
  "app_version": "1.0",
  "app_platform": "ios",
  "usage_limit": 0,
  "user_details": {
    "firstName": "John",
    "lastName": "Doe",
    "phoneNumber": "0031612345678",
    "authenticationLevel": "1",
    "email": "john.doe@example.com"
  },
  "amr": [
    "DEFAULT",
    "FINGER_PRINT",
    "CUSTOM_AUTHENTICATOR",
    "IMPLICIT_AUTHENTICATION"
  ]
}

Example token introspection response for an invalid access token:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "active": false
}

Token introspection API

Require scope

Request parameters

Custom attributes

Examples

On this page

Suggest A Change