> ## 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.

# JSON Web Key Set for access-token verification

> Public keys a resource server (or the FastAPI middleware) uses to
verify access-token signatures locally, without a per-request call to
MudraID. Returns every key currently valid for verification — the
active signing key plus rotated-but-not-retired keys.

Cache it, and refetch immediately on an unknown `kid`. The endpoint
sets `Cache-Control: public, max-age=3600` (shorter when serving a
last-known-good set).




## OpenAPI

````yaml /openapi.yaml get /.well-known/jwks.json
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:
  /.well-known/jwks.json:
    get:
      tags:
        - resource-server
      summary: JSON Web Key Set for access-token verification
      description: |
        Public keys a resource server (or the FastAPI middleware) uses to
        verify access-token signatures locally, without a per-request call to
        MudraID. Returns every key currently valid for verification — the
        active signing key plus rotated-but-not-retired keys.

        Cache it, and refetch immediately on an unknown `kid`. The endpoint
        sets `Cache-Control: public, max-age=3600` (shorter when serving a
        last-known-good set).
      responses:
        '200':
          description: Key set
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JWKS'
        '503':
          description: |
            Key discovery is temporarily unavailable and no key set has been
            served yet by this instance. Retry; keep using a cached set.
components:
  schemas:
    JWKS:
      type: object
      required:
        - keys
      properties:
        keys:
          type: array
          items:
            $ref: '#/components/schemas/JWK'
    JWK:
      type: object
      required:
        - kty
        - use
        - alg
        - kid
        - 'n'
        - e
      properties:
        kty:
          type: string
          enum:
            - RSA
        use:
          type: string
          enum:
            - sig
        alg:
          type: string
          enum:
            - RS256
        kid:
          type: string
        'n':
          type: string
          description: RSA modulus, base64url no padding
        e:
          type: string
          description: RSA exponent, base64url no padding

````

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