Token Introspection

Endpoint:
POST /relid/authserver/oauth/introspect

Description:
Allows clients to verify the validity and metadata of an access or refresh token. This is useful to confirm if a token is active and obtain information such as scopes, expiry, and user ID.

🔐 Authentication

Type: Basic Auth
Header Format: Authorization: Basic <base64(client_id:client_secret)>

📥 Request Headers

Header	Value
Authorization	Basic authentication credentials
Content-Type	application/x-www-form-urlencoded
Accept	application/json

📤 Request Body (Form URL Encoded)

Field	Type	Required	Description
`token`	string	Yes	The token to be introspected
`token_type_hint`	string	No	Hint about the type of token (`access_token` or `refresh_token`)

📥 Query Parameters

No query parameters.

📬 Response Fields

Field	Type	Description
`active`	boolean	Indicates if the token is currently active
`scope`	string	Space-separated list of scopes associated with the token
`client_id`	string	Client ID the token was issued to
`username`	string	User ID tied to the token
`exp`	number	Expiry time (Unix timestamp)
`sub`	string	Subject of the token
`aud`	array	Audience for the token
`nbf`	number	Not valid before this timestamp
`jti`	string	JWT ID
`iss`	string	Issuer of the token
`iat`	number	Issued at (Unix timestamp)
`token_type`	string	Type of the token (e.g., Bearer)

📘 Example Request (cURL)

curl 'https://auth.relid.com:8006/relid/authserver/oauth/introspect' \
  -u '<client_id>:<client_secret>' \
  -X POST \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'Accept: application/json' \
  -d 'token=<access_token>&token_type_hint=access_token'

📘 Example Response

{
  "active": true,
  "sub": "ZDcyOTY1YjgtYjhlZS00ZDAyLWE5NjUtYjhiOGVlY2QwMjA1",
  "aud": ["gm-api-server", "idv-web-server", "OIDC"],
  "nbf": 1726050259,
  "scope": "all",
  "iss": "https://auth.relid.com",
  "exp": 1726053859,
  "iat": 1726050259,
  "jti": "66b5c480-ffea-4861-9b15-f589ba7e9d03",
  "client_id": "ZDcyOTY1YjgtYjhlZS00ZDAyLWE5NjUtYjhiOGVlY2QwMjA1",
  "username": "ZDcyOTY1YjgtYjhlZS00ZDAyLWE5NjUtYjhiOGVlY2QwMjA1",
  "token_type": "Bearer"
}

📝 Notes

Only tokens issued by this AuthServer are supported.
This is especially useful when tokens are passed between services for authorization.
NOTE: Request parameters must be provided in the request body, not the URL.

Updated 3 months ago