Manage Identities

Agent identities are org-scoped and identified by a unique agent_handle. Handles are normalized — a leading @ is automatically stripped, so @my-agent and my-agent are equivalent.

POST /identities

Create a new agent identity. The handle must be unique within your organization. You can optionally create and link a mailbox, provision and link a phone number, and attach access to existing vault secrets in the same request.

Request body

mailbox fields

phone_number fields

vault_secret_ids

Use this to attach existing vault secret access to the new identity. The organization must already have an active vault. If omitted, no vault secret access is attached.

Accepted forms:

• A single stringified UUID to attach one secret
• A list of UUIDs to attach specific secrets
• "all" or "*" to attach all active secrets in the active vault

Request example

JSON

Response (201)

JSON

If mailbox is omitted, the identity is still created successfully and email_address is null. If phone_number is omitted, the identity is created without a linked phone number. If vault_secret_ids is omitted, the identity is created without any vault secret access.

Mailbox local-part validation

When you provide mailbox.email_local_part, it must satisfy these rules:

• Length: 3–64 characters
• Characters: lowercase letters, numbers, hyphens (-), underscores (_), and dots (.)
• Start/end: must begin and end with a letter or number
• No consecutive dots: my..agent is rejected
• No @: provide the handle only, not a full email address
• Reserved names blocked: common system addresses (e.g. admin, postmaster, noreply, support, billing) and similar restricted names are rejected. Separator variants are normalized before validation.

Error responses

Code examples

cURL

cURL

JavaScript

Python

GET /identities

List all non-deleted identities for your organization, newest first.

Response (200)

JSON

Code examples

cURL

cURL

JavaScript

Python

GET /identities/{agent_handle}

Get a single identity with its linked communication channels. The detail response includes nested mailbox and phone number objects. Channel assignment endpoints also return this same detail model.

Path parameters

Response (200)

JSON

If no mailbox or phone number is assigned, those fields are null.

Error responses

Code examples

cURL

cURL

JavaScript

Python

PATCH /identities/{agent_handle}

Update an identity's handle or status. Only supplied fields are modified.

Path parameters

Request body

Request example

JSON

Response (200)

JSON

Error responses

Code examples

cURL

cURL

JavaScript

Python

DELETE /identities/{agent_handle}

Delete an identity. Any assigned mailbox or phone number is unlinked (but not deleted — they remain available for reassignment). Returns 204 No Content on success.

Path parameters

Code examples

cURL

cURL

JavaScript

Python

Extends the identity object with linked channel data. Returned by the get and channel assignment endpoints.