Token Revocation

Overview

The revocation endpoint allows a client to invalidate a token it no longer needs. This is typically used for logout flows or when a token's privilege level changes. Once revoked:

• For OAuth2 (opaque) tokens: the token is deleted immediately and can no longer be used
• For JWT tokens: the refresh token is invalidated, but the access token remains valid until its natural expiry (use introspection to detect revoked refresh tokens)

Endpoint

Mode	Method	Endpoint
Manage From This Policy	POST	https://yourApinizerAddress/auth/revoke
Manage From ACL	POST	https://yourApinizerAddress/credential/revoke

Request

Headers

Header	Value	Required
Content-Type	application/x-www-form-urlencoded	Yes
Authorization	Basic (base64-encoded credentials)	Yes

Authentication

Revocation requires HTTP Basic authentication, using the same credentials as the token endpoint:

Authorization: Basic base64(client_id:client_secret)

• In "Manage From This Policy" mode: Use the application key and secret.
• In "Manage From ACL" mode: Use the credential's client ID and secret.

Request Body

Parameter	Type	Required	Description
token	string	Yes	The token value to revoke
token_type_hint	string	No	Optional hint: access_token or refresh_token

Example Request

curl -X POST \
  "https://yourApinizerAddress/auth/revoke" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -H "Authorization: Basic $(echo -n 'your-app-key:your-app-secret' | base64)" \
  -d "token=the_token_value"

Response

Success (200 OK)

A successful revocation request returns HTTP 200 with an empty response body:

HTTP/1.1 200 OK

Note

Per RFC 7009, the server returns HTTP 200 for both successful revocations and for unknown tokens. This prevents information leakage about which tokens exist.

Token Type Behavior

How revocation behaves depends on the token type:

• OAuth2 (opaque) tokens: The stored token is deleted. Because access and refresh tokens are kept together, revoking either one invalidates both immediately.
• JWT tokens: Revocation applies to the refresh token. A revoked refresh JWT can no longer be exchanged for a new token. The access token itself remains valid until its own short expiry time. For immediate per-token revocation, use OAuth2 (opaque) tokens instead.

Error Responses

400 Bad Request — Missing or Malformed Parameters

{
  "error": "invalid_request",
  "error_description": "The token parameter is required."
}

Possible causes:

• Missing token parameter
• Malformed request body
• Invalid Content-Type header

401 Unauthorized — Authentication Failed

{
  "error": "invalid_client",
  "error_description": "Authentication failed. Check your credentials."
}

Possible causes:

• Missing or invalid Authorization header
• Incorrect client_id or client_secret
• Basic auth decoding failed

503 Service Unavailable

{
  "error": "server_error",
  "error_description": "The token store is temporarily unavailable."
}

If the token store is temporarily unavailable, the revocation endpoint returns HTTP 503 instead of a false success. This signals to the client that the token was not revoked and should retry the request later.

Warning

A 503 response means the revocation did not succeed. The client should retry, as the token remains valid until revocation completes successfully.

Best Practices

• Logout flows: Revoke the access token on logout to invalidate it immediately (for opaque tokens) or revoke the refresh token (for JWTs).
• Check 503 errors: If revocation returns 503, the client cannot be certain the token was revoked. Treat the token as potentially valid until a retry succeeds.
• Cross-client revocation: A client can only revoke tokens it issued; attempting to revoke another client's token returns HTTP 200 (per RFC) but has no effect.

Related Pages

• Token Issuance Endpoints — Obtain tokens
• Token Introspection — Check token validity
• Discovery & JWKS — Discover endpoints and public keys