Skip to content
machinemail

Agent Registrations

Agent registrations bound to the organization.

MethodPathSummary
GET/v0/agent-registrationsList Agent Registrations
GET/v0/agent-registrations/{agent_id}Get Agent Registration
DELETE/v0/agent-registrations/{agent_id}Revoke Agent Registration

List Agent Registrations

http
GET /v0/agent-registrations

Agent registrations bound to the organization. Requires an organization-scoped credential with api_key_read; pod, inbox and sandbox credentials get 403.

Authentication: Authorization: Bearer <api key> or the dashboard mm_session cookie. Permission: api_key_read.

Query parameters

limitinteger
Maximum number of items to return. Default 50, maximum 500; larger values are capped.
page_tokenstring
next_page_token from the previous page.
ascendingboolean
Sort oldest first.
status"pending_claim" | "claimed" | "revoked"
Only registrations with this status.

Response

200 A page of registrations (application/json)

countintegerRequired
Number of items returned.
limitinteger
Maximum number of items per page. Default 50, maximum 500; larger values are capped.
next_page_tokenstring
Page token for pagination. Absent on the last page.
agent_registrationsAgentRegistration[]Required
Newest first unless ascending is set.

Each item of agent_registrations is a AgentRegistration:

agent_idstringRequired
ID of the registration (reg_...).
registration_idstringRequired
Same value as agent_id.
registration_type"anonymous" | "service_auth" | "identity_assertion"Required
anonymous: no human yet; a sandbox inbox until a human claims it. service_auth: on behalf of a named user, who confirms first. identity_assertion: an ID-JAG from a trusted agent provider.
status"pending_claim" | "claimed" | "revoked"Required
namestring
Agent-described label. Untrusted.
clientstring
Provider name for identity_assertion, otherwise agent (self-described) or anonymous agent.
organization_idstring
Organization the registration is bound to (after a claim, or right away for identity_assertion).
inbox_idstring
The sandbox inbox of an anonymous registration.
emailstring
Verified email bound at claim or carried by the identity assertion.
issuerstring
Issuer of the identity assertion (identity_assertion).
agent_platformstring
agent_platform claim of the identity assertion.
created_atstring (date-time)Required
When the agent registered.
claimed_atstring (date-time)
When a human claimed the registration.
revoked_atstring (date-time)
When the registration was revoked.
expires_atstring (date-time)
When an unclaimed registration expires.

Errors

StatusMeaning
400Invalid request: error.type is validation and error.param names the field.
401Missing, invalid, expired or revoked credential.
403The credential lacks the permission or scope for this request (error.type forbidden), or MachineMail suspended the organization or its sending (account_suspended: error.message says what still works; do not retry or re-register).
500Unexpected server error.

Error bodies use the error envelope.

Example

Request
curl "https://api.machinemail.dev/v0/agent-registrations" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY"
Response 200
{
  "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"
    }
  ]
}

Get Agent Registration

http
GET /v0/agent-registrations/{agent_id}

Requires an organization-scoped credential with api_key_read.

Authentication: Authorization: Bearer <api key> or the dashboard mm_session cookie. Permission: api_key_read.

Path parameters

agent_idstringRequired
ID of the registration.

Response

200 The registration (application/json)

agent_idstringRequired
ID of the registration (reg_...).
registration_idstringRequired
Same value as agent_id.
registration_type"anonymous" | "service_auth" | "identity_assertion"Required
anonymous: no human yet; a sandbox inbox until a human claims it. service_auth: on behalf of a named user, who confirms first. identity_assertion: an ID-JAG from a trusted agent provider.
status"pending_claim" | "claimed" | "revoked"Required
namestring
Agent-described label. Untrusted.
clientstring
Provider name for identity_assertion, otherwise agent (self-described) or anonymous agent.
organization_idstring
Organization the registration is bound to (after a claim, or right away for identity_assertion).
inbox_idstring
The sandbox inbox of an anonymous registration.
emailstring
Verified email bound at claim or carried by the identity assertion.
issuerstring
Issuer of the identity assertion (identity_assertion).
agent_platformstring
agent_platform claim of the identity assertion.
created_atstring (date-time)Required
When the agent registered.
claimed_atstring (date-time)
When a human claimed the registration.
revoked_atstring (date-time)
When the registration was revoked.
expires_atstring (date-time)
When an unclaimed registration expires.

Errors

StatusMeaning
401Missing, invalid, expired or revoked credential.
403The credential lacks the permission or scope for this request (error.type forbidden), or MachineMail suspended the organization or its sending (account_suspended: error.message says what still works; do not retry or re-register).
404Not found. Also returned for resources outside the credential scope.
500Unexpected server error.

Error bodies use the error envelope.

Example

Request
curl "https://api.machinemail.dev/v0/agent-registrations/string" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY"
Response 200
{
  "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"
}

Revoke Agent Registration

http
DELETE /v0/agent-registrations/{agent_id}

Revokes the registration; its tokens stop working immediately. Returns the registration with status: revoked (revoking twice is not an error). Requires an organization-scoped credential with api_key_delete.

Authentication: Authorization: Bearer <api key> or the dashboard mm_session cookie. Permission: api_key_delete.

Path parameters

agent_idstringRequired
ID of the registration.

Response

200 The revoked registration (application/json)

agent_idstringRequired
ID of the registration (reg_...).
registration_idstringRequired
Same value as agent_id.
registration_type"anonymous" | "service_auth" | "identity_assertion"Required
anonymous: no human yet; a sandbox inbox until a human claims it. service_auth: on behalf of a named user, who confirms first. identity_assertion: an ID-JAG from a trusted agent provider.
status"pending_claim" | "claimed" | "revoked"Required
namestring
Agent-described label. Untrusted.
clientstring
Provider name for identity_assertion, otherwise agent (self-described) or anonymous agent.
organization_idstring
Organization the registration is bound to (after a claim, or right away for identity_assertion).
inbox_idstring
The sandbox inbox of an anonymous registration.
emailstring
Verified email bound at claim or carried by the identity assertion.
issuerstring
Issuer of the identity assertion (identity_assertion).
agent_platformstring
agent_platform claim of the identity assertion.
created_atstring (date-time)Required
When the agent registered.
claimed_atstring (date-time)
When a human claimed the registration.
revoked_atstring (date-time)
When the registration was revoked.
expires_atstring (date-time)
When an unclaimed registration expires.

Errors

StatusMeaning
401Missing, invalid, expired or revoked credential.
403The credential lacks the permission or scope for this request (error.type forbidden), or MachineMail suspended the organization or its sending (account_suspended: error.message says what still works; do not retry or re-register).
404Not found. Also returned for resources outside the credential scope.
500Unexpected server error.

Error bodies use the error envelope.

Example

Request
curl -X DELETE "https://api.machinemail.dev/v0/agent-registrations/string" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY"
Response 200
{
  "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"
}

On this page

List Agent RegistrationsGet Agent RegistrationRevoke Agent Registration
0% read