{
  "title": "Agent Registrations",
  "description": "List, inspect and revoke the agents that registered themselves through auth.md and are bound to your MachineMail organization. Needs an organization key.",
  "canonical": "https://machinemail.dev/docs/reference/api/agent-registrations",
  "content": {
    "methods": [
      {
        "method": "GET",
        "path": "/v0/agent-registrations",
        "summary": "List Agent Registrations"
      },
      {
        "method": "GET",
        "path": "/v0/agent-registrations/{agent_id}",
        "summary": "Get Agent Registration"
      },
      {
        "method": "DELETE",
        "path": "/v0/agent-registrations/{agent_id}",
        "summary": "Revoke Agent Registration"
      }
    ],
    "queries": {
      "List Agent Registrations": {
        "parameters": [
          { "field": "limit", "type": "integer", "description": "Maximum number of items to return. Default 50, maximum 500; larger values are capped." },
          { "field": "page_token", "type": "string", "description": "next_page_token from the previous page." },
          { "field": "ascending", "type": "boolean", "description": "Sort oldest first." },
          { "field": "status", "type": "string", "options": ["pending_claim", "claimed", "revoked"], "description": "Only registrations with this status." }
        ]
      }
    },
    "responses": {
      "200": {
        "description": "A page of registrations",
        "schema": {
          "type": "object",
          "fields": [
            { "field": "count", "type": "integer", "required": true, "description": "Number of items returned." },
            { "field": "limit", "type": "integer", "description": "Maximum number of items per page." },
            { "field": "next_page_token", "type": "string", "description": "Page token for pagination." },
            {
              "field": "agent_registrations",
              "type": "array",
              "items": {
                "type": "object",
                "fields": [
                  { "field": "agent_id", "type": "string", "required": true, "description": "ID of the registration (reg_...)." },
                  { "field": "registration_id", "type": "string", "required": true, "description": "Same value as agent_id." },
                  { "field": "registration_type", "type": "string", "options": ["anonymous", "service_auth", "identity_assertion"], "required": true, "description": "Type of registration." },
                  { "field": "status", "type": "string", "options": ["pending_claim", "claimed", "revoked"], "required": true, "description": "Status of the registration." },
                  { "field": "name", "type": "string", "description": "Agent-described label." },
                  { "field": "client", "type": "string", "description": "Provider name for identity_assertion." },
                  { "field": "organization_id", "type": "string", "description": "Organization the registration is bound to." },
                  { "field": "inbox_id", "type": "string", "description": "The sandbox inbox of an anonymous registration." },
                  { "field": "email", "type": "string", "description": "Verified email bound at claim." },
                  { "field": "issuer", "type": "string", "description": "Issuer of the identity assertion." },
                  { "field": "agent_platform", "type": "string", "description": "agent_platform claim of the identity assertion." },
                  { "field": "created_at", "type": "string (date-time)", "required": true, "description": "When the agent registered." },
                  { "field": "claimed_at", "type": "string (date-time)", "description": "When a human claimed the registration." },
                  { "field": "revoked_at", "type": "string (date-time)", "description": "When the registration was revoked." },
                  { "field": "expires_at", "type": "string (date-time)", "description": "When an unclaimed registration expires." }
                ]
              }
            }
          ]
        }
      }
    },
    "examples": {
      "requests": {
        "request": "curl \"https://api.machinemail.dev/v0/agent-registrations\" -H \"Authorization: Bearer $MACHINEMAIL_API_KEY\""
      },
      "responses": {
        "response": {
          "count": 1,
          "limit": 50,
          "next_page_token": "eyJvIjo1MH0",
          "agent_registrations": [
            {
              "agent_id": "string",
              "registration_id": "string",
              "registration_type": "anonymous",
              "status": "pending_claim",
              "name": "Production",
              "client": "string",
              "organization_id": "org_01k6x2m9qd0000a7h3kq9v2c4e",
              "inbox_id": "agent@machinemail.dev",
              "email": "agent@machinemail.dev",
              "issuer": "string",
              "agent_platform": "string",
              "created_at": "2026-10-01T12:00:00.000Z",
              "claimed_at": "2026-10-01T12:00:00.000Z",
              "revoked_at": "2026-10-01T12:00:00.000Z",
              "expires_at": "2026-10-01T12:00:00.000Z"
            }
          ]
        }
      }
    }
  }
}