# Revoke a token

OAuth 2.0 token revocation (RFC 7009). Revokes an access token or a refresh token;
revoking a refresh token revokes its whole token family. The endpoint returns `200`
even when the token is already invalid, as required by the RFC.
Confidential clients authenticate with HTTP Basic (`client_secret_basic`); public
clients send their `client_id` in the form body. A client revokes only its own tokens:
a token of another client is left untouched and still answers `200`.

Endpoint: POST /oauth/revoke
Version: 3.0.0-preview

## Request fields (application/x-www-form-urlencoded):

  - `token` (string, required)
    The access or refresh token to revoke.

  - `token_type_hint` (string)
    Optional RFC 7009 hint. Accepted and ignored: the token prefix (`ag_at_`, `ag_rt_`) defines the type.
    Enum: "access_token", "refresh_token"

  - `client_id` (string)
    Required for public clients. Confidential clients send it in HTTP Basic and omit this field.

## Response 200:

  - `200` (unknown)
    The token has been revoked (or was already invalid).

## Response 400:

  - `400` (unknown)
    The `token` parameter is missing (RFC 6749 error object).

## Response 400 fields (application/json):

  - `error` (string, required)
    OAuth error code (`invalid_request`, `invalid_grant`, `invalid_client`, ...).

  - `error_description` (string)

## Response 401:

  - `401` (unknown)
    Client authentication failed (RFC 6749 error object).

## Response 401 fields (application/json):

  - `error` (string, required)
    OAuth error code (`invalid_request`, `invalid_grant`, `invalid_client`, ...).

  - `error_description` (string)

## Response 429:

  - `429` (unknown)
    Too many revocation requests for this client or address. Retry after the interval in
`Retry-After`; a `429` does not mean the token survived — re-send the same request.

## Response 429 fields (application/json):

  - `error` (string, required)
    OAuth error code (`invalid_request`, `invalid_grant`, `invalid_client`, ...).

  - `error_description` (string)

## Response 429 headers (application/json):

  - `Retry-After` (integer)
    Seconds to wait before retrying.
    Example: 60

## Response 500:

  - `500` (unknown)
    Revocation could not be completed because of an unexpected server error (OAuth error
object). The token may still be valid — retry until the endpoint returns `200`.

## Response 500 fields (application/json):

  - `error` (string, required)
    OAuth error code (`invalid_request`, `invalid_grant`, `invalid_client`, ...).

  - `error_description` (string)

## Response 503:

  - `503` (unknown)
    A revocation dependency is unavailable (OAuth error object). The token may still be
valid — back off and retry until the endpoint returns `200`.

## Response 503 fields (application/json):

  - `error` (string, required)
    OAuth error code (`invalid_request`, `invalid_grant`, `invalid_client`, ...).

  - `error_description` (string)