---
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"
---

# Agent Registrations

> List, inspect and revoke the agents that registered themselves through auth.md and are bound to your MachineMail organization. Needs an organization key.

Source: https://machinemail.dev/docs/reference/api/agent-registrations

| Method   | Path                                 | Summary                                                 |
| -------- | ------------------------------------ | ------------------------------------------------------- |
| `GET`    | `/v0/agent-registrations`            | [List Agent Registrations](#list-agent-registrations)   |
| `GET`    | `/v0/agent-registrations/{agent_id}` | [Get Agent Registration](#get-agent-registration)       |
| `DELETE` | `/v0/agent-registrations/{agent_id}` | [Revoke Agent Registration](#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

| Field | Type | | Description |
| --- | --- | --- | --- |
| `limit` | `integer` |  | Maximum number of items to return. Default 50, maximum 500; larger values are capped. |
| `page_token` | `string` |  | next_page_token from the previous page. |
| `ascending` | `boolean` |  | Sort oldest first. |
| `status` | `"pending_claim" \| "claimed" \| "revoked"` |  | Only registrations with this status. |

#### Response

**200** A page of registrations (`application/json`)

| Field | Type | | Description |
| --- | --- | --- | --- |
| `count` | `integer` | required | Number of items returned. |
| `limit` | `integer` |  | Maximum number of items per page. Default 50, maximum 500; larger values are capped. |
| `next_page_token` | `string` |  | Page token for pagination. Absent on the last page. |
| `agent_registrations` | `AgentRegistration[]` | required | Newest first unless ascending is set. |

Each item of `agent_registrations` is a [AgentRegistration](https://machinemail.dev/docs/reference/api/objects#agentregistration):

| Field | Type | | Description |
| --- | --- | --- | --- |
| `agent_id` | `string` | required | ID of the registration (reg_...). |
| `registration_id` | `string` | required | 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 |  |
| `name` | `string` |  | Agent-described label. Untrusted. |
| `client` | `string` |  | Provider name for identity_assertion, otherwise agent (self-described) or anonymous agent. |
| `organization_id` | `string` |  | Organization the registration is bound to (after a claim, or right away for identity_assertion). |
| `inbox_id` | `string` |  | The sandbox inbox of an anonymous registration. |
| `email` | `string` |  | Verified email bound at claim or carried by the identity assertion. |
| `issuer` | `string` |  | Issuer of the identity assertion (identity_assertion). |
| `agent_platform` | `string` |  | agent_platform claim of the identity assertion. |
| `created_at` | `string (date-time)` | required | When the agent registered. |
| `claimed_at` | `string (date-time)` |  | When a human claimed the registration. |
| `revoked_at` | `string (date-time)` |  | When the registration was revoked. |
| `expires_at` | `string (date-time)` |  | When an unclaimed registration expires. |

#### Errors

| Status | Meaning                                                                                                                                                                                                                                |
| ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400`  | Invalid request: error.type is validation and error.param names the field.                                                                                                                                                             |
| `401`  | Missing, invalid, expired or revoked credential.                                                                                                                                                                                       |
| `403`  | The 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). |
| `500`  | Unexpected server error.                                                                                                                                                                                                               |

Error bodies use the [error envelope](https://machinemail.dev/docs/reference/errors).

#### Example

```bash title="Request"
curl "https://api.machinemail.dev/v0/agent-registrations" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY"
```

```json title="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

| Field | Type | | Description |
| --- | --- | --- | --- |
| `agent_id` | `string` | required | ID of the registration. |

#### Response

**200** The registration (`application/json`)

| Field | Type | | Description |
| --- | --- | --- | --- |
| `agent_id` | `string` | required | ID of the registration (reg_...). |
| `registration_id` | `string` | required | 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 |  |
| `name` | `string` |  | Agent-described label. Untrusted. |
| `client` | `string` |  | Provider name for identity_assertion, otherwise agent (self-described) or anonymous agent. |
| `organization_id` | `string` |  | Organization the registration is bound to (after a claim, or right away for identity_assertion). |
| `inbox_id` | `string` |  | The sandbox inbox of an anonymous registration. |
| `email` | `string` |  | Verified email bound at claim or carried by the identity assertion. |
| `issuer` | `string` |  | Issuer of the identity assertion (identity_assertion). |
| `agent_platform` | `string` |  | agent_platform claim of the identity assertion. |
| `created_at` | `string (date-time)` | required | When the agent registered. |
| `claimed_at` | `string (date-time)` |  | When a human claimed the registration. |
| `revoked_at` | `string (date-time)` |  | When the registration was revoked. |
| `expires_at` | `string (date-time)` |  | When an unclaimed registration expires. |

#### Errors

| Status | Meaning                                                                                                                                                                                                                                |
| ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `401`  | Missing, invalid, expired or revoked credential.                                                                                                                                                                                       |
| `403`  | The 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). |
| `404`  | Not found. Also returned for resources outside the credential scope.                                                                                                                                                                   |
| `500`  | Unexpected server error.                                                                                                                                                                                                               |

Error bodies use the [error envelope](https://machinemail.dev/docs/reference/errors).

#### Example

```bash title="Request"
curl "https://api.machinemail.dev/v0/agent-registrations/string" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY"
```

```json title="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

| Field | Type | | Description |
| --- | --- | --- | --- |
| `agent_id` | `string` | required | ID of the registration. |

#### Response

**200** The revoked registration (`application/json`)

| Field | Type | | Description |
| --- | --- | --- | --- |
| `agent_id` | `string` | required | ID of the registration (reg_...). |
| `registration_id` | `string` | required | 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 |  |
| `name` | `string` |  | Agent-described label. Untrusted. |
| `client` | `string` |  | Provider name for identity_assertion, otherwise agent (self-described) or anonymous agent. |
| `organization_id` | `string` |  | Organization the registration is bound to (after a claim, or right away for identity_assertion). |
| `inbox_id` | `string` |  | The sandbox inbox of an anonymous registration. |
| `email` | `string` |  | Verified email bound at claim or carried by the identity assertion. |
| `issuer` | `string` |  | Issuer of the identity assertion (identity_assertion). |
| `agent_platform` | `string` |  | agent_platform claim of the identity assertion. |
| `created_at` | `string (date-time)` | required | When the agent registered. |
| `claimed_at` | `string (date-time)` |  | When a human claimed the registration. |
| `revoked_at` | `string (date-time)` |  | When the registration was revoked. |
| `expires_at` | `string (date-time)` |  | When an unclaimed registration expires. |

#### Errors

| Status | Meaning                                                                                                                                                                                                                                |
| ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `401`  | Missing, invalid, expired or revoked credential.                                                                                                                                                                                       |
| `403`  | The 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). |
| `404`  | Not found. Also returned for resources outside the credential scope.                                                                                                                                                                   |
| `500`  | Unexpected server error.                                                                                                                                                                                                               |

Error bodies use the [error envelope](https://machinemail.dev/docs/reference/errors).

#### Example

```bash title="Request"
curl -X DELETE "https://api.machinemail.dev/v0/agent-registrations/string" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY"
```

```json title="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"
}
```