Understanding Token Revocation and When to Use It

sequenceDiagram
    participant App as Client Application
    participant AuthServer as Authorization Server
    participant Resource as Resource Server

    App->>AuthServer: 1. Client Credentials (client_id + secret)
    AuthServer->>AuthServer: 2. Validate Credentials
    AuthServer->>App: 3. Access Token
    App->>Resource: 4. API Request with Token
    Resource->>App: 5. Protected Resource

Token revocation is a critical security feature in OAuth 2.0 that allows clients or authorization servers to invalidate access or refresh tokens before their natural expiration. This capability enhances control over user sessions and reduces risks in compromised environments.

What Is Token Revocation?

Token revocation is the process by which an access or refresh token is deliberately invalidated, rendering it unusable for further API access or token renewal. Unlike token expiration, revocation is immediate and intentional.

Why Use Token Revocation?

• User logout: Invalidate tokens when a user explicitly logs out.

• Security breaches: Revoke tokens suspected to be compromised or leaked.

• Permission changes: When user permissions or roles change, revoke old tokens to enforce new policies.

• Application uninstall: Revoke tokens if a client app is uninstalled or access is withdrawn.

OAuth 2.0 Token Revocation Endpoint (RFC 7009)

RFC 7009 defines a standard /revoke endpoint. Clients POST a token with credentials to immediately invalidate it. The server returns HTTP 200 regardless of token validity — this prevents attackers from probing which tokens are still valid.

Revocation request example (cURL):

curl -X POST "https://auth.example.com/oauth2/revoke" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "token=REFRESH_TOKEN" \
  -d "token_type_hint=refresh_token" \
  -d "client_id=your_client_id" \
  -d "client_secret=your_client_secret"

• token: The access or refresh token to revoke.
• token_type_hint (optional): access_token or refresh_token — helps the server search efficiently.
• Client credentials authenticate the request to prevent abuse.

Provider-Specific Revocation

Keycloak: The endpoint follows {url}/realms/{realm}/protocol/openid-connect/revoke. Revoking a refresh token also terminates the associated SSO session.

curl -X POST "https://keycloak.example.com/realms/myrealm/protocol/openid-connect/revoke" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "token=$REFRESH_TOKEN&token_type_hint=refresh_token&client_id=myclient&client_secret=$CLIENT_SECRET"

If you’re diagnosing why a token was invalidated unexpectedly, check our guide on Keycloak session expired errors — session timeouts and token revocation can look identical from the client’s perspective.

Auth0: Call POST https://your-domain.auth0.com/oauth/revoke with a JSON body:

curl -X POST "https://your-tenant.auth0.com/oauth/revoke" \
  -H "Content-Type: application/json" \
  -d '{"client_id":"...","client_secret":"...","token":"REFRESH_TOKEN"}'

Okta: Use POST https://{yourOktaDomain}/oauth2/v1/revoke. Revoking a refresh token invalidates all access tokens derived from it.

How Authorization Servers Handle Revocation

Upon receiving a valid revocation request:

• The server immediately marks the token as revoked in its store.
• The token becomes invalid for any further use.
• Associated refresh tokens may also be revoked depending on policy (cascading revocation).
• HTTP 200 is returned regardless of token validity.

Access token revocation caveat: If resource servers validate JWTs locally (without calling the authorization server), they won’t know about the revocation until the token expires. Two solutions:

1. Use OAuth 2.0 token introspection — resource servers call the AS to validate tokens in real time.
2. Keep access token lifetimes short (15–60 minutes) so revocation of the refresh token limits exposure.

For understanding what’s inside the tokens you’re revoking, the JWT Decoder tool lets you inspect access token claims without writing code.

When to Revoke vs. When to Let Tokens Expire

For failed token exchanges that surface as invalid_grant errors — which happen when tokens are expired or already revoked — see the OAuth invalid_grant complete troubleshooting guide.

Best Practices for Token Revocation

• Implement revocation endpoints conforming to RFC 7009.
• Require client authentication for revocation requests to prevent abuse.
• Log revocation events for auditing and incident response.
• Consider cascading revocation for tokens derived from a revoked refresh token.
• Combine revocation with short-lived access tokens and refresh token rotation.

Real-World Scenario

A banking app detects a stolen device. The user triggers a global logout from a different device. The system revokes all refresh tokens for that device immediately. Because access tokens are short-lived (15 minutes), exposure is capped. Resource servers using token introspection know instantly; those doing local JWT validation wait out the 15-minute window.

Summary

Token revocation (RFC 7009) enables immediate invalidation of OAuth tokens for security events like logout, device loss, and permission changes. Pair revocation with short access token lifetimes and token introspection for defense-in-depth that doesn’t sacrifice performance.