Token Management — IdP API
Endpoints for token lifecycle management including introspection (RFC 7662) and revocation (RFC 7009). Use these to validate or invalidate tokens.
Base URL: https://idp.authpi.com — explore every endpoint in the
interactive IdP API reference.
POST/{issuer_id}/introspect
Token Introspection
Validates a token and returns its metadata (RFC 7662).
Use this endpoint to determine if an access token or refresh token is currently active and retrieve information about it. This is useful for:
- Resource servers validating access tokens before granting access
- Applications checking token validity without decoding the JWT
- Audit systems retrieving token metadata
Authorization
Clients can only introspect tokens they issued. If a client attempts to introspect a token issued to a different client, the response will indicate active: false without revealing that the token exists (per RFC 7662 security requirements).
Response
active: true- Token is valid and can be usedactive: false- Token is invalid, expired, revoked, or the client is not authorized to introspect it
When active: true, the response includes token claims such as sub, scope, exp, iat, and custom claims.
Token Type Detection
If token_type_hint is not provided, the endpoint automatically detects the token type based on its claims. However, providing the hint can improve performance.
Specification: RFC 7662 - OAuth 2.0 Token Introspection
Request body
Content type: application/x-www-form-urlencoded
| Property | Type | Required | Description |
|---|---|---|---|
token | string | Required | The access token or refresh token to introspect |
token_type_hint | access_token | refresh_token | Optional | Hint about the token type to optimize lookup. If not provided, the endpoint will attempt to detect the type automatically. |
client_id | string | Optional | Client ID. Required for confidential clients not using HTTP Basic auth. |
client_secret | string | Optional | Client secret, when authenticating via the request body (client_secret_post). |
Responses
| Code | Description | Schema |
|---|---|---|
| 200 | Token Introspection Response | IntrospectionResponse |
| 400 | Bad Request - The request is malformed or missing required parameters. | OAuthError |
| 401 | Unauthorized - Authentication is required or has failed. | OAuthError |
| 403 | Forbidden - The authenticated client or user lacks permission for this operation. | OAuthError |
| 404 | Not Found - The requested resource does not exist. | OAuthError |
| 422 | Unprocessable Entity - The request syntax is correct but the data cannot be processed. | OAuthError |
| 429 | Too Many Requests - Rate limit exceeded. | OAuthError |
| 500 | Internal Server Error - An unexpected error occurred. | OAuthError |
POST/{issuer_id}/revoke
Token Revocation
Revokes an access token or refresh token (RFC 7009).
Use this endpoint to invalidate tokens when:
- A user logs out
- A user revokes application access
- A token is suspected of being compromised
- Security policies require token invalidation
Revocation Behavior
Refresh tokens: Revocation invalidates the refresh token via the Session Manager. All future attempts to use the token will fail.
Access tokens: Revocation adds the token to a revocation list. The token remains technically valid until it expires, but API calls will fail validation. This approach balances security with performance for short-lived tokens.
Authorization
The client revoking the token must either:
- Be the client that originally requested the token
- Have user credentials with appropriate permissions
Response
Per RFC 7009, this endpoint always returns a success response (200 OK) regardless of whether the token was valid. This prevents token enumeration attacks.
Specification: RFC 7009 - OAuth 2.0 Token Revocation
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
issuer_id | string | Required | The unique identifier for the issuer/tenant |
Request body
Content type: application/x-www-form-urlencoded
| Property | Type | Required | Description |
|---|---|---|---|
token | string | Required | The access token or refresh token to revoke |
token_type_hint | access_token | refresh_token | Optional | Hint about the token type. Providing this improves performance but is not required. |
client_id | string | Optional | Client ID. Required for confidential clients not using HTTP Basic auth. |
client_secret | string | Optional | Client secret, when authenticating via the request body (client_secret_post). |
Responses
| Code | Description | Schema |
|---|---|---|
| 200 | Success - Token revoked (or was already invalid). | object |
| 400 | Bad Request - The request is malformed or missing required parameters. | OAuthError |
| 401 | Unauthorized - Authentication is required or has failed. | OAuthError |
| 403 | Forbidden - The authenticated client or user lacks permission for this operation. | OAuthError |
| 404 | Not Found - The requested resource does not exist. | OAuthError |
| 422 | Unprocessable Entity - The request syntax is correct but the data cannot be processed. | OAuthError |
| 429 | Too Many Requests - Rate limit exceeded. | OAuthError |
| 500 | Internal Server Error - An unexpected error occurred. | OAuthError |