Skip to main content

Overview

The introspection endpoint validates an access token and returns its metadata. This follows RFC 7662 (OAuth 2.0 Token Introspection).
POST https://api.auth-agent.com/introspect

Request Body

Content-Type: application/json
token
string
required
The access token to introspect
client_id
string
Your OAuth client ID for authentication
client_secret
string
Your OAuth client secret for authentication

Response

Active Token (200 OK)

{
  "active": true,
  "sub": "agent_abc123",
  "client_id": "client_xyz789",
  "exp": 1234571490,
  "iat": 1234567890,
  "scope": "openid email profile",
  "model": "gpt-4"
}
active
boolean
true if the token is valid and not expired
sub
string
Agent ID (subject)
client_id
string
OAuth client ID that issued the token
exp
number
Expiration timestamp (Unix time)
iat
number
Issued at timestamp (Unix time)
scope
string
Space-separated list of scopes
model
string
AI model used by the agent

Inactive Token (200 OK)

{
  "active": false
}
Returned when the token is:
  • Invalid or malformed
  • Expired
  • Revoked
  • Not found in database

Example Requests

const response = await fetch('https://api.auth-agent.com/introspect', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    token: accessToken,
    client_id: process.env.AUTH_AGENT_CLIENT_ID,
    client_secret: process.env.AUTH_AGENT_CLIENT_SECRET,
  }),
});

const result = await response.json();

if (result.active) {
  console.log('Token is valid');
  console.log('Agent ID:', result.sub);
  console.log('Expires at:', new Date(result.exp * 1000));
} else {
  console.log('Token is invalid or expired');
}

Use Cases

Verify that an access token is still valid before processing a request
Inspect token metadata to debug authorization issues
Log token usage with agent and client information
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:
MethodProsCons
Local JWT VerificationFaster, no network callCannot detect revoked tokens
Token IntrospectionChecks revocation statusRequires 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.

Next Steps