> ## 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 JWT verification

> The platform middleware fetches this to verify JWT signatures locally
without per-request MudraID calls. Returns every key currently
considered valid for verification — that is, the active signing key
plus any `previous` (rotated-but-not-retired) keys.

Cache hint: middleware should cache for ~1 hour and refresh
immediately on encountering an unknown `kid`. The endpoint sets
`Cache-Control: public, max-age=3600`.




## OpenAPI

````yaml /openapi.yaml get /.well-known/jwks.json
openapi: 3.0.3
info:
  title: MudraID Public Contracts (v1)
  version: 1.0.0
  description: |
    This document defines the **stable public contracts** between MudraID and
    the Python Agent SDK + FastAPI Platform Middleware. Per-service
    administrative and internal endpoints are intentionally omitted here —
    they are documented by each FastAPI service's auto-generated
    `/openapi.json` at runtime and may evolve more freely.

    What lives in *this* file (and may not change without a v1 deprecation
    window):

      - `POST /api/v1/auth/token` — agent → JWT exchange
      - `POST /api/v1/auth/agents/me/platforms` — SDK bootstrap
      - `GET /.well-known/jwks.json` — JWKS for platform middleware
      - `GET /api/v1/platforms/{platform_id}/scopes.yaml` — scope file for middleware
      - JWT claim shape
      - mudraid_scopes.yaml schema
servers:
  - url: https://api.mudraid.ai
    description: Production
security: []
tags:
  - name: agent-sdk
    description: |
      Endpoints called by the Python Agent SDK. These contracts are stable
      v1 — any breaking change requires a deprecation cycle.
  - name: platform-middleware
    description: |
      Endpoints called by the FastAPI Platform Middleware. Stable v1.
paths:
  /.well-known/jwks.json:
    get:
      tags:
        - platform-middleware
      summary: JSON Web Key Set for JWT verification
      description: |
        The platform middleware fetches this to verify JWT signatures locally
        without per-request MudraID calls. Returns every key currently
        considered valid for verification — that is, the active signing key
        plus any `previous` (rotated-but-not-retired) keys.

        Cache hint: middleware should cache for ~1 hour and refresh
        immediately on encountering an unknown `kid`. The endpoint sets
        `Cache-Control: public, max-age=3600`.
      responses:
        '200':
          description: Key set
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JWKS'
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
          example: muid_sk_a3f8...32hex
        'n':
          type: string
          description: RSA modulus, base64url no padding
        e:
          type: string
          description: RSA exponent, base64url no padding

````