Overview
The introspection endpoint validates an access token and returns its metadata. This follows RFC 7662 (OAuth 2.0 Token Introspection).Request Body
Content-Type:application/json
The access token to introspect
Your OAuth client ID for authentication
Your OAuth client secret for authentication
Response
Active Token (200 OK)
true if the token is valid and not expiredAgent ID (subject)
OAuth client ID that issued the token
Expiration timestamp (Unix time)
Issued at timestamp (Unix time)
Space-separated list of scopes
AI model used by the agent
Inactive Token (200 OK)
- Invalid or malformed
- Expired
- Revoked
- Not found in database
Example Requests
Use Cases
Token Validation
Token Validation
Verify that an access token is still valid before processing a request
Debugging
Debugging
Inspect token metadata to debug authorization issues
Audit Logging
Audit Logging
Log token usage with agent and client information
Rate Limiting
Rate Limiting
Implement rate limiting based on agent ID or client ID
Introspection vs JWT Verification
You can verify tokens locally by validating the JWT signature, or use introspection:| Method | Pros | Cons |
|---|---|---|
| Local JWT Verification | Faster, no network call | Cannot detect revoked tokens |
| Token Introspection | Checks revocation status | Requires API call |
For most use cases, local JWT verification is sufficient. Use introspection if you need to check revocation status or don’t want to implement JWT validation.
