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

# Download the platform's scope file

> The platform's `mudraid_scopes.yaml`: its active scope catalogue and
its route → scope mappings, in the order the middleware must match
them. The FastAPI middleware reads it at startup to build its
route → required-scope map. The portal download emits the same bytes.

Authenticated with the platform's own API key (`X-Api-Key` plus
`X-Api-Secret`, holding the `platform:verify` scope). A key for one
platform cannot read another platform's file.

Returned as `text/plain`; structure documented in the
`MudraidScopesYaml` component.




## OpenAPI

````yaml /openapi.yaml get /api/v1/platforms/{platform_id}/scopes.yaml
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:
  /api/v1/platforms/{platform_id}/scopes.yaml:
    get:
      tags:
        - resource-server
      summary: Download the platform's scope file
      description: |
        The platform's `mudraid_scopes.yaml`: its active scope catalogue and
        its route → scope mappings, in the order the middleware must match
        them. The FastAPI middleware reads it at startup to build its
        route → required-scope map. The portal download emits the same bytes.

        Authenticated with the platform's own API key (`X-Api-Key` plus
        `X-Api-Secret`, holding the `platform:verify` scope). A key for one
        platform cannot read another platform's file.

        Returned as `text/plain`; structure documented in the
        `MudraidScopesYaml` component.
      parameters:
        - in: path
          name: platform_id
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: scopes.yaml body
          content:
            text/plain:
              schema:
                type: string
                description: YAML body conforming to MudraidScopesYaml
        '401':
          description: >-
            Missing or invalid platform API credentials
            (`UNAUTHORIZED_PLATFORM_API_KEY`).
        '403':
          description: |
            The key lacks `platform:verify` (`FORBIDDEN_PLATFORM_SCOPE`), or
            belongs to a different platform (`PLATFORM_TENANT_MISMATCH`).
        '429':
          description: Platform API rate limit exceeded (`RATE_LIMIT_EXCEEDED`).
      security:
        - platformApiKey: []
          platformApiSecret: []
components:
  securitySchemes:
    platformApiKey:
      type: apiKey
      in: header
      name: X-Api-Key
    platformApiSecret:
      type: apiKey
      in: header
      name: X-Api-Secret

````

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