An agent identity is the persistent "person" your agent presents to the outside world. It has a globally unique handle (like a username) and owns exactly one mailbox and one tunnel; it can optionally be granted a phone number, opt into iMessage, and hold access to specific vault secrets. Every email your agent sends, every call it makes, and every inbound request its tunnel routes comes from this single, consistent entity.

Call create_identity() with a handle — a globally unique slug for your agent. The identity, its mailbox, and its tunnel are provisioned atomically in a single call; you can optionally provision a phone number and opt into iMessage (imessage_enabled: true) in the same request. The returned object already has its channels populated — no follow-up create_mailbox / create_tunnel step.

The tunnel is always created in edge TLS mode unless you opt into passthrough via the nested tunnel body.

identity.mailbox and identity.tunnel are non-null for every live identity. Read them directly off the returned object rather than calling get_identity() afterwards.

The tunnel is reachable at identity.tunnel.public_host (e.g. sales-bot.inkboxwire.com) but isn't routing traffic yet. To bring it online, open the data-plane connection with inkbox.tunnels.connect(tunnel_id=identity.tunnel.id, forward_to=...); see the Tunnels capability guide for forwarding modes, in-process handlers, and Passthrough TLS for CSR signing.

The mailbox and tunnel are atomic with identity create. A phone number is opt-in — either inline at create time (via the phone_number body, as above) or provisioned on an existing identity. Each identity supports at most one phone number, and a number stays bound to the identity it was provisioned on for its lifetime.

When your agent restarts or you need to rehydrate state, fetch the identity by its handle. get_identity() returns the identity with its current channel state attached.

Agent identities are invisible to each other by default. An agent using an agent-scoped API key sees only itself when it calls list_identities() or get_identity() — until you grant it visibility on a peer. Granting visibility is how agents in the same org discover and reach each other.

Grant one specific viewer, or open the identity to the whole org with the wildcard (pass None / null). Revoking a viewer from a wildcard-visible identity first materializes it into explicit per-viewer grants, so the revoke narrows visibility without un-sharing the identity from everyone else.

Admin-scoped API keys and the Inkbox Console always see every identity regardless of these grants — visibility only narrows what agent-scoped keys can see. In the Console, manage it under Contacts → Agents.

See the Agent visibility API reference for the underlying endpoints, status codes, and the access-rule object.

Identities are long-lived resources. You'll update them as your agents evolve — renaming them, pausing them during off-hours, or retiring them entirely.

Update the handle, display name, description, iMessage reachability, or status. Setting status to "paused" is useful for temporarily disabling an agent without losing its channels or history. PATCH semantics: omitting a field leaves it unchanged; passing null (or None in Python) clears it on nullable fields like display_name and description.

Renaming on the platform domain. When the linked mailbox is on the platform domain (inkboxmail.com), the handle doubles as the mailbox name ({handle}@inkboxmail.com), so renaming would break inbound delivery — the rename is rejected with 409. Identities on custom sending domains can be renamed freely.

Release a phone number when you want to give it up while keeping the identity active. The number is returned to the carrier and removed from your account. The mailbox and tunnel are owned 1:1 by the identity and cannot be released separately — delete the identity if you want everything gone.

Delete the identity when the agent is being fully retired. The linked mailbox and tunnel are deleted as part of the cascade, and any identity-scoped API keys tied to this identity are revoked. Any linked phone number is released back to the carrier as part of the cascade.