# Revoke OAuth token

Revokes the token named, every other live token the same user holds for the same OAuth client, and every authorization code that user was issued for the client and has not yet exchanged. Both halves of a credential live on one row, so each refresh token is closed with its access token. All of them stop working immediately, and the client must be authorized again to get a new token.
The wide reach is deliberate. An administrator revokes to contain a leaked credential, and a refresh leaves the row it replaced usable until the new token is first used -- after which the database no longer records which rows came before it. Closing the user's whole authorization is what leaves no part of it usable. Unexchanged codes go too, because whoever holds one can trade it for a new token pair without the user taking part.
One call does not settle the matter: a refresh already in flight can add a live token just after the revocation reads the rows. Re-list, and revoke again if anything remains.
Administrators only, authenticated by an apikey or a session; an OAuth bearer token is refused. Requires the `eng-lc-oauth-token-management` launch control flag on the account.
Answers 404 whether the id is malformed, names no token, names a token in another account, or names one that is already revoked.
A client closing a credential it holds itself uses `POST /oauth/revoke` (RFC 7009), which revokes that credential and the rows a refresh still links to it, and leaves the user's other tokens for the client alone.

Endpoint: POST /oauth_token/remove/{oauth_token_id}
Version: 3
Security: ApiKeyAuth

## Path parameters:

  - `oauth_token_id` (integer, required)

## Response 200 fields (application/json):

  - `oauth_token` (object, required)
    An OAuth credential issued to a client on behalf of a user. The token and refresh token strings are secrets and are never included.

  - `oauth_token.id` (integer, required)
    unique identifier of the token
    Example: 123

  - `oauth_token.client` (any, required)
    the OAuth client the token was issued to. `null` for a token issued without a client

  - `oauth_token.client.id` (integer, required)
    unique identifier of the client
    Example: 456

  - `oauth_token.client.name` (string, required)
    the name of the client

  - `oauth_token.created_at` (string, required)
    when the token was issued

  - `oauth_token.expired` (boolean, required)
    whether the access half has expired. An expired token is still listed, because a `refreshable` one can be exchanged for a new access token until the row is revoked -- a refresh token never expires

  - `oauth_token.expires_at` (string, required)
    when the access half expires. `null` for a token that never expires

  - `oauth_token.refreshable` (boolean, required)
    whether the token carries a refresh token

  - `oauth_token.scopes` (string, required)
    the scopes granted to the token, space separated

  - `oauth_token.sub_user` (boolean, required)
    whether the owner is a sub user

  - `oauth_token.user` (any, required)
    the user the token was issued on behalf of. `null` when the user no longer resolves

  - `oauth_token.user.id` (integer, required)
    unique identifier of the user
    Example: 123

  - `oauth_token.user.email` (string, required)
    the email of the user

  - `oauth_token.user.name` (string, required)
    the display name of the user