Token Revocation

Token Revocation

Token revocation is the process by which a client provides either an access token or refresh token which is then invalidated by the server.

Process

---
title: Token Revocation
---
sequenceDiagram
autonumber

actor Client
participant Authorization Service
participant Data Layer

Client-->>Authorization Service: Calls the revoke endpoint with token_type_hint and token params
Note right of Client: POST /oauth/revoke
Authorization Service-->Authorization Service: Determines most efficient OAuth session retrieval strategy for provided hint
Authorization Service-->Authorization Service: Decodes token
Authorization Service-->>Data Layer: Retrieves OAuth session via retrieval strategy
Authorization Service-->>Data Layer: Marks OAuth session as revoked
Authorization Service-->>Client: Returns HTTP ok status

Loading

Client

The Client entity represents a client application registered with the OAuth provider.

Authorization Service

The Authorization Service entity represents the component of the application which is responsible for invalidating the OAuth session for the provided token. This is provided by TokenAuthority.

Data Layer

The Data Layer entity is a relational database used for storing data related to OAuth sessions.

Endpoints

POST /oauth/revoke

The client calls the POST /oauth/revoke endpoint to revoke the OAuth session associated with an access or refresh token. Per RFC-7009, the endpoint responds with HTTP status 200 OK regardless of whether the token is successfully revoked or not. This prevents token probing attacks.

HTTP Method: POST

URL: /oauth/revoke

Content-Type: application/x-www-form-urlencoded

Params:

Param	Required?	Description
token	yes	The access or refresh token to be revoked.
token_type_hint	no	The type of token provided; used for efficient retrieval of OAuth session. Can be either access_token or refresh_token.

Example Request:

POST /oauth/revoke
Content-Type: application/x-www-form-urlencoded

token=eyJhbGciOiJIUzI1NiJ9.eyJhdWQiOiJodHRwOi8vbG9jYWxob3N0OjMwMDAvYXBpLyIsImlhdCI6MTY5NTE0MDY1NiwiaXNzIjoiaHR0cDovL2xvY2FsaG9zdDozMDAwLyIsImp0aSI6IjUxMGJhNTdiLTgwNTQtNGQxYi1iYWQ1LTVmZmZjOWE0NzA4ZCIsImV4cCI6MTY5NjM1MDI1Nn0.6-7DgP4UFcA7hEkK7XRob_sRNEGH1QlvalysDJjBrko&
token_type_hint=refresh_token

Response:

The endpoint returns HTTP 200 OK with an empty body on success.

Error Response:

{
    "error": "unsupported_token_type"
}

The unsupported_token_type error is returned if the token cannot be decoded as a valid JWT.

Behavior Notes

• When a session is revoked, both the access token and refresh token for that session become invalid.
• The token_type_hint parameter is optional but recommended. It helps the server locate the session more efficiently by searching the appropriate column first.
• If token_type_hint is not provided, the server will attempt to decode the token and look up the session by the token's JTI claim.
• Revoking an already-revoked token is not an error; the endpoint will still return HTTP 200 OK.

References

• OAuth 2.1 IETF Draft
• RFC-7009: OAuth 2.0 Token Revocation