Jump to

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, iMessage settings, or status

/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}

Agent visibility

Agent identities are invisible to each other by default — an agent-scoped API key sees only its own identity on list and get. Grant visibility so agents in the same org can discover and reach each other, either per-viewer or org-wide. See Agent visibility for the full reference.

Grant visibility

POST

Grant a viewer identity visibility on the target, or open the target to every agent in the org

/api/v1/identities/{agent_handle}/access

List visibility

GET

List who can currently see the target identity

/api/v1/identities/{agent_handle}/access

Revoke visibility

DELETE

Revoke a viewer identity's visibility on the target

/api/v1/identities/{agent_handle}/access/{viewer_identity_id}

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

Vault API
Mail API
Phone API
iMessage API — opt identities in with imessage_enabled