Validating OAuth 2.0 Access Tokens with Ory Hydra's Token Introspection Endpoint

Desired outcome

Confirm that an OAuth 2.0 access token issued by Ory Hydra is still valid, active, and authorized for the required scopes before allowing a service to access a protected resource.

Prerequisites

• An operational Ory Hydra instance (version 2.x) reachable over HTTPS.
• The client ID and secret of the OAuth 2.0 client that originally issued the token.
• The access token string you want to validate.
• Ability to make HTTP POST requests (e.g., using curl or an HTTP client library).

Procedure

1. Construct the introspection URL: https:///oauth2/introspect. Replace <hydra-host> with your Hydra domain or IP.
2. Authenticate using HTTP Basic auth with the client ID as username and client secret as password.
3. Send a POST request with a JSON body containing the token parameter:

curl -u ":" \
     -X POST \
     -H "Content-Type: application/json" \
     -d '{"token":""}' \
     "https:///oauth2/introspect"

Replace placeholders:

• <client-id> – the OAuth client identifier.
• <client-secret> – the client secret.
• <access-token> – the token to validate.
• <hydra-host> – hostname of your Hydra deployment.

Expected checks

The server returns a JSON object. Treat the token as valid only if:

• The field active is present and equals true.
• The scope field (space‑separated list) contains every scope required by your service.
• The client_id matches the expected client (helps prevent token confusion attacks).
• The exp claim (Unix timestamp) is greater than the current time.

If active is missing, false, or any of the above checks fail, consider the token invalid.

Recovery options

When the introspection indicates an invalid token:

• Log the event (including token hash, client ID, and reason) for audit.
• If your application supports refresh tokens, initiate a refresh token grant to obtain a new access token.
• Return an HTTP 401 Unauthorized response to the caller, optionally with a WWW-Authenticate: Bearer header.

Limitations and practical verification

Introspection adds network latency and load on Hydra. To mitigate:

• Cache the introspection result for the token’s remaining lifetime (derived from exp minus a safety margin).
• Ensure TLS is enabled; otherwise client credentials and token data travel in clear text.
• Avoid calling introspection on every request for high‑traffic APIs; use the cache strategy above.

You can verify the setup locally:

1. Start a test Hydra instance (e.g., via Docker: docker run -d -p 4444:4444 -e SECRETS_SYSTEM=mysecret ory/hydra:v2.0.0 serve all --dangerous-force-http).
2. Create a client with the client credentials grant: hydra clients create --id test-client --secret test-secret --grant-types client_credentials --response-types token --scope offline access.
3. Obtain an access token: curl -u "test-client:test-secret" -X POST "http://localhost:4444/oauth2/token" -d "grant_type=client_credentials&scope=offline".
4. Run the introspection command shown above with the obtained token and confirm active:true and the expected scopes.
5. Repeat with an expired token (you can manually set exp in a JWT or wait) and verify active:false or missing.