Skip to main content

​
Overview

The revocation endpoint allows clients to revoke access or refresh tokens. This follows RFC 7009 (OAuth 2.0 Token Revocation). 
POST https://api.auth-agent.com/revoke

​
Request Body

Content-Type: application/json
​
token
string
required
The access or refresh token to revoke
​
client_id
string
required
Your OAuth client ID
​
client_secret
string
required
Your OAuth client secret

​
Response

​
Success (200 OK)

{
  "revoked": true
}
The endpoint returns success even if the token was already revoked or doesn’t exist, following RFC 7009 security recommendations.

​
Error (401 Unauthorized)

{
  "error": "invalid_client",
  "error_description": "Invalid client credentials"
}

​
Example Requests

// Revoke refresh token (also revokes associated access token)
await fetch('https://api.auth-agent.com/revoke', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    token: refreshToken,
    client_id: process.env.AUTH_AGENT_CLIENT_ID,
    client_secret: process.env.AUTH_AGENT_CLIENT_SECRET,
  }),
});

// Clear stored tokens
delete req.session.tokens;

​
Revocation Behavior

When you revoke a refresh token, the associated access token is also revoked. This ensures complete session termination.
When you revoke an access token, only that specific token is invalidated. The refresh token remains valid.
Calling revoke on an already-revoked token returns success. This is intentional for security reasons per RFC 7009.
Due to refresh token rotation, revoking any token in a refresh chain does not automatically revoke other tokens in that family. Each token must be explicitly revoked.

​
Use Cases

User Logout

Revoke tokens when a user logs out to invalidate their session

Security Incident

Immediately revoke tokens if a security breach is detected

Token Cleanup

Revoke old tokens during token refresh or session cleanup

Account Deletion

Revoke all tokens when an account is deleted or disabled

​
Security Considerations

Always revoke refresh tokens during logout. Revoking only the access token leaves the session partially active.
Client authentication is required to prevent unauthorized token revocation.

​
Next Steps

Token Lifecycle

Learn about token expiration and management

Security Best Practices

Implement secure token handling