Token Introspection

Token introspection lets a resource server ask LumoAuth whether a token is still valid and retrieve metadata about it (client, user, scopes, expiration). This endpoint implements RFC 7662 — OAuth 2.0 Token Introspection: an authorized resource server calls /introspect to ask LumoAuth whether a token is still valid.

POST /orgs/{orgId}/api/v1/oauth/introspect

When to Use Introspection

Scenario	Recommendation
Opaque tokens	Required — opaque tokens can only be validated via introspection
JWT tokens (normal validation)	Not needed — validate the signature and expiration locally against the JWKS for better performance
JWT tokens (check for revocation)	Recommended for sensitive operations — local JWT validation cannot detect revocation
Getting token metadata	Use introspection when you need current scopes, user ID, or other claims

Authentication

Call this endpoint from your backend using your client credentials. Never call it from client-side code.

Request

Parameter	Required	Description
token	Yes	The token to validate
token_type_hint	No	access_token or refresh_token — speeds up lookup

Example Request

curl -X POST https://app.lumoauth.dev/orgs/acme-corp/api/v1/oauth/introspect \
  -u "CLIENT_ID:CLIENT_SECRET" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "token=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -d "token_type_hint=access_token"

Response

Active Token

{
  "active": true,
  "scope": "openid profile email",
  "client_id": "abc123def456",
  "username": "john@example.com",
  "token_type": "Bearer",
  "exp": 1704067200,
  "iat": 1704063600,
  "sub": "12345",
  "aud": "api.example.com",
  "iss": "https://app.lumoauth.dev"
}

Inactive / Invalid Token

If the token is expired, revoked, malformed, or does not exist, the response is simply:

{
  "active": false
}

The server intentionally returns the same response for all invalid-token cases, so an attacker cannot distinguish between "unknown token" and "revoked token".

Response Fields

Field	Type	Description
active	boolean	Always present. Whether the token is currently valid.
scope	string	Space-separated list of granted scopes
client_id	string	Which client the token was issued to
sub	string	Subject — user ID or agent ID
exp	integer	Expiration timestamp (Unix epoch seconds)
iat	integer	Issued-at timestamp
iss	string	Issuer URL
aud	string	Intended audience

Related

• Token formats — local JWT validation
• Security considerations