Skip to main content
POST
Revoke Token

Revoke Token

Revokes an OAuth access token. The endpoint follows RFC 7009 semantics: revocation is idempotent and silent — unknown or already-revoked tokens still return 200 success. On a successful revoke the server:
  1. Locates the app installation that owns this accessToken.
  2. Blacklists both the access token and its paired refresh token for 31 days (only a hash of each token is stored, never the raw value).
  3. Clears the stored access token, refresh token, and their expiry timestamps on the installation.
The installation itself is not deleted — status remains active. The merchant must call POST /apps/store/uninstall/:appId for a full uninstall. This endpoint is rate-limited to 5 requests per minute per IP.

Request

Body Parameters

string
required
The access token to revoke. Refresh tokens cannot be revoked directly — passing one returns 200 (silent no-op) because no installation row matches a refresh token in the accessToken lookup. To kill a refresh token, revoke its paired access token (which blacklists both) or wait 30 days for natural expiry.

Response

integer
Always 200.
string
Always success.
string
Token revoked successfully. Returned for both genuine revocations and unknown tokens (RFC 7009 §2.2 idempotency).

Example Response

What gets revoked

When the server finds an installation matching the supplied access token, both tokens on that row are blacklisted and cleared in a single update: Subsequent /api/v1/* calls with either token are rejected by the auth guard with the standard { errors } error body:
(The specific message Token has been revoked only appears when a blacklisted refresh token is replayed at the token endpoint.)

When to revoke

  • User-initiated sign-out of your app’s embedded UI.
  • Compromised token suspicion — pair with rotating client_secret via POST /apps/developer/:appId/regenerate-secret.
  • Switching environments between dev/staging/prod for the same app installation.
Revoking does not uninstall the app, surrender granted scopes, or notify the merchant. For a full uninstall + webhook fan-out, see POST /apps/store/uninstall/:appId.

Ending a session (alternatives)

Error Codes

Security Notes

  • Token blacklist entries live for 31 days — one day longer than the longest possible refresh-token lifetime — so a revoked token can never come back via a stale cache.
  • Only a SHA-256 hash of the token is stored in the blacklist; the raw token is never persisted.
  • This endpoint has no auth requirement beyond rate limiting — anyone holding a valid access token can revoke it. This is intentional: a leaked token should be invalidatable from any environment without needing the original client_secret.