agent registrations.md

{ "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" } ] } } } } }