> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mudraid.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Revoke a token (RFC 7009)

> Revokes a rotating refresh token and its whole family for the
authenticated client. Client authentication is `client_secret_basic`,
or `none` with a form `client_id` for a client registered as a public
client.

Always answers `200` with an empty body — for a valid, unknown,
already-revoked or non-refresh token, and when authentication fails —
so this endpoint cannot be used to probe token validity. Machine
clients receive no refresh tokens, and an access token is not revoked
here: it stays valid until it expires, while revoking the grant or
containing the client stops new tokens. The endpoint is advertised in
the authorization-server metadata (`revocation_endpoint`) only when the
refresh-token capability is enabled; otherwise it is a no-op.




## OpenAPI

````yaml /openapi.yaml post /oauth2/revoke
openapi: 3.0.3
info:
  title: MudraID Public Contracts
  version: 2.0.0
  description: >
    This document defines the **public contracts** an integrator calls

    directly: the OAuth endpoints an agent's machine client uses to obtain an

    access token, the discovery documents a resource server verifies those

    tokens with, the scope file the FastAPI middleware loads, and the live

    decision endpoint enforcement adapters call. Administrative and internal

    endpoints are intentionally omitted — they are documented by each FastAPI

    service's auto-generated `/openapi.json` at runtime and may evolve more

    freely.


    What lives in *this* file:

      - `POST /oauth2/token` — machine-client `client_credentials` exchange
      - `POST /oauth2/revoke` — RFC 7009 token revocation
      - `GET /.well-known/oauth-authorization-server` — RFC 8414 metadata
      - `GET /.well-known/jwks.json` — token-verification keys
      - `GET /api/v1/platforms/{platform_id}/scopes.yaml` — scope file for the middleware
      - `POST /api/v1/adapter/enforcement/decide` — live decision for one protected action
      - the access-token claim shape and the `mudraid_scopes.yaml` schema

    **Retired native agent credentials.** `POST /api/v1/auth/token`,

    `POST /api/v1/auth/verify`, `POST /api/v1/auth/agents/me/platforms`,

    `POST /api/v1/agents/register`, `PUT
    /api/v1/agents/{agent_id}/permissions/{platform_id}`

    and `POST /api/v1/agents/{agent_id}/rotate-secret` (and its `/emergency`

    variant) answer `410 Gone` with `code: agent_native_credentials_retired`.

    Register an agent identity (`POST /api/v1/agents/identities`), link an

    OAuth machine client to it and use `POST /oauth2/token`. Every

    `/api/v1/verify/*` path also answers `410 Gone` with the same code.
servers:
  - url: https://api.mudraid.ai
    description: Production
security: []
tags:
  - name: oauth
    description: |
      OAuth 2.0 endpoints. A machine client linked to an agent authenticates
      here with `private_key_jwt` (recommended) or, with an organization
      compatibility approval, `client_secret_basic`.
  - name: resource-server
    description: |
      Documents a protected API (or the FastAPI middleware) reads to verify
      access tokens and enforce route scopes.
  - name: enforcement
    description: |
      The live decision endpoint called by enforcement adapters (the V2
      middleware, the Node adapter/sidecar and the Kong plugin).
paths:
  /oauth2/revoke:
    post:
      tags:
        - oauth
      summary: Revoke a token (RFC 7009)
      description: |
        Revokes a rotating refresh token and its whole family for the
        authenticated client. Client authentication is `client_secret_basic`,
        or `none` with a form `client_id` for a client registered as a public
        client.

        Always answers `200` with an empty body — for a valid, unknown,
        already-revoked or non-refresh token, and when authentication fails —
        so this endpoint cannot be used to probe token validity. Machine
        clients receive no refresh tokens, and an access token is not revoked
        here: it stays valid until it expires, while revoking the grant or
        containing the client stops new tokens. The endpoint is advertised in
        the authorization-server metadata (`revocation_endpoint`) only when the
        refresh-token capability is enabled; otherwise it is a no-op.
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
                - token
              properties:
                token:
                  type: string
                  description: The token to revoke.
                token_type_hint:
                  type: string
                  description: Advisory hint, e.g. `refresh_token`.
                client_id:
                  type: string
                  description: Public-client identification (`none` method only).
      responses:
        '200':
          description: Empty body, whatever the outcome.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.