When building secure APIs, validating tokens is critical. But not all tokens are self-contained (like JWTs). That’s where OAuth 2.0 Token Introspection comes in — a mechanism to verify token status, scope, and expiration in real time via the authorization server.

What Is Token Introspection?

Token introspection is defined in RFC 7662. It allows a protected resource (like your API server) to ask the authorization server:

“Is this token valid? What does it contain?”

This is especially useful for:

  • Opaque tokens (e.g., random strings)
  • Session-based tokens
  • Additional trust when validating JWTs

Example Introspection Request (cURL)

curl -X POST https://auth.example.com/oauth2/introspect \
  -u "client-id:client-secret" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

The response:

{
  "active": true,
  "username": "alice",
  "scope": "read write",
  "client_id": "my-client",
  "exp": 1717595390,
  "iat": 1717591790
}

🔐 If active is false, the token has been revoked, expired, or is invalid.

When to Use Token Introspection

Use Case Recommended?
Validating JWT tokens ❌ Usually not needed (validate locally)
Validating opaque tokens ✅ Yes
Extra security for APIs ✅ Optional
Dynamic revocation checks ✅ Yes

If you need real-time checks for revocation or scope changes, introspection adds that safety layer — even for JWTs.

Java Example Using Spring and RestTemplate

// Java method to introspect a token and check if it's active
public boolean isTokenActive(String token) {
  RestTemplate restTemplate = new RestTemplate();
  
  HttpHeaders headers = new HttpHeaders();
  headers.setBasicAuth("your-client-id", "your-client-secret");
  headers.setContentType(MediaType.APPLICATION_FORM_URLENCODED);

  MultiValueMap<String, String> body = new LinkedMultiValueMap<>();
  body.add("token", token);

  HttpEntity<MultiValueMap<String, String>> request = new HttpEntity<>(body, headers);
  ResponseEntity<Map> response = restTemplate.postForEntity(
    "https://auth.example.com/oauth2/introspect", request, Map.class);

  return Boolean.TRUE.equals(response.getBody().get("active"));
}

✅ You can also extract scopes and user information from the response to enforce business logic.

ForgeRock-Specific Tips

ForgeRock Identity Cloud and AM support token introspection as part of their OAuth2 provider.

  • Enable the introspection endpoint in the OAuth2 provider config
  • Use Identity Gateway (IG) or AM policy agents to delegate introspection
  • Combine with session management to reflect login/logout states

Best Practices

  • 🔄 Cache introspection responses for short TTLs to reduce overhead
  • 🔐 Secure the endpoint using client credentials (never expose it to browsers)
  • 🧪 Use introspection to support RBAC and fine-grained API access control

👉 Related:

How to Revoke OAuth 2.0 Tokens and Secure Your Applications

Understanding the Authorization Code Flow with PKCE in OAuth 2.0

How to Implement the OAuth 2.0 Authorization Code Flow in Java

Conclusion: Don’t Trust Blindly — Introspect When Necessary

OAuth 2.0 token introspection allows your applications to verify access tokens dynamically. Especially when dealing with opaque tokens or high-security environments, introspection ensures that only valid, unrevoked tokens are accepted.

🧠 Should your APIs trust tokens without checking their status? 🔍 Are you validating scopes and expiration in real time?

In the next post, we’ll explore how to build secure logout and session management with ForgeRock and OAuth2.