Skip to content

Agent identity API

An agent identity is the unit of presence on Inkbox. Each identity owns exactly one mailbox and one tunnel; you can optionally attach a phone number and vault-secret access. Handles are globally unique across all Inkbox customers.

API base URL:

https://inkbox.ai/api/v1/identities

Quick start

Create an account and get your API key from the Inkbox console:

Get API key

All API requests require authentication using a API key:

X-API-Key: YOUR_API_KEY

Identities

Create identity

POST

Atomically provisions the identity, its mailbox, and its tunnel; optional phone number, description, and vault secrets

/api/v1/identities

List identities

GET

List all identities for your organization

/api/v1/identities

Get identity

GET

Get a single identity with its linked channels

/api/v1/identities/{agent_handle}

Update identity

PATCH

Update an identity's handle, display name, description, or iMessage settings

/api/v1/identities/{agent_handle}

Delete identity

DELETE

Deletes the identity and cascades the delete to the linked mailbox and tunnel; releases any linked phone number

/api/v1/identities/{agent_handle}

Identity access (retired)

Identity visibility grants have been replaced by the Agent2Agent directories and A2A contact rules. The legacy paths return 410 Gone; see the retirement notice.

Phone-number release

The mailbox and tunnel are atomic with identity create/delete — they are provisioned at creation and destroyed at deletion. Phone numbers are provisioned bound to an identity (via POST /phone/numbers) and released as a separate operation.

Release phone number

DELETE

Release the identity's phone number back to the carrier

/api/v1/identities/{agent_handle}/phone_number

Additional resources