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, become reachable by other agents over A2A, 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-scoped credentials read only their own identity through the identities API. Use the Agent2Agent directories to discover other agents and A2A contact rules to control communication.

Identities are long-lived resources. You'll update them as your agents evolve — renaming them, changing their configuration, or retiring them entirely.

Update the handle, display name, description, iMessage reachability, or contact-rule filter modes. 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.