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

# List the calling agent's platforms (SDK bootstrap)

> Called once at SDK startup so the Agent can build its URL→platform_id
routing map. POST (not GET) because credentials live in the body —
the JWT path isn't usable yet at this point in the bootstrap.

Hostnames in the response come from each platform's verified domain;
they may be `null` if upstream metadata is temporarily unavailable.
SDK callers should treat enrichment fields as best-effort.




## OpenAPI

````yaml /openapi.yaml post /api/v1/auth/agents/me/platforms
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:
  /api/v1/auth/agents/me/platforms:
    post:
      tags:
        - agent-sdk
      summary: List the calling agent's platforms (SDK bootstrap)
      description: |
        Called once at SDK startup so the Agent can build its URL→platform_id
        routing map. POST (not GET) because credentials live in the body —
        the JWT path isn't usable yet at this point in the bootstrap.

        Hostnames in the response come from each platform's verified domain;
        they may be `null` if upstream metadata is temporarily unavailable.
        SDK callers should treat enrichment fields as best-effort.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AgentPlatformsRequest'
      responses:
        '200':
          description: Platform list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentPlatformsResponse'
        '401':
          description: Invalid credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Agent inactive
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    AgentPlatformsRequest:
      type: object
      required:
        - api_key_id
        - secret
      properties:
        api_key_id:
          type: string
        secret:
          type: string
    AgentPlatformsResponse:
      type: object
      required:
        - agent_id
        - platforms
      properties:
        agent_id:
          type: string
          format: uuid
        platforms:
          type: array
          items:
            $ref: '#/components/schemas/AgentPlatformItem'
    Error:
      type: object
      required:
        - detail
      properties:
        detail:
          type: string
          description: Human-readable error message.
        error_code:
          type: string
          description: |
            Machine-readable code (where surfaced). The token endpoint uses
            generic "invalid credentials" for both unknown-id and wrong-secret
            cases to resist enumeration.
    AgentPlatformItem:
      type: object
      required:
        - platform_id
        - granted_scopes
        - status
      properties:
        platform_id:
          type: string
          format: uuid
        granted_scopes:
          type: array
          items:
            type: string
        status:
          type: string
          enum:
            - active
            - revoked
        name:
          type: string
          nullable: true
          description: Human-readable platform name (enrichment; may be null).
        hostname:
          type: string
          nullable: true
          description: |
            Verified platform domain — the host the SDK will see in outgoing
            request URLs. Used to map URL host → platform_id. May be null if
            platform-integration-service was unavailable when the response
            was built.
        verification_status:
          type: string
          enum:
            - pending
            - verified
            - rejected
            - expired
          nullable: true

````