Identities

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.

Creating an identity

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. Treat description as public copy. It appears on the Agent Card when the identity is claimed and A2A is enabled, even if the identity is absent from the public directory.

identity = inkbox.create_identity(
    "sales-bot",
    display_name="Sales Bot",
    description="Sales-outreach agent owned by the GTM team.",
    tunnel={"tls_mode": "edge"},
    phone_number={"type": "local"},
)
print(identity.mailbox.email_address)  # e.g. sales-bot@inkboxmail.com
print(identity.tunnel.public_host)     # e.g. sales-bot.inkboxwire.com
print(identity.tunnel.zone)            # inkboxwire.com
print(identity.phone_number.number)    # e.g. +14155550100

const identity = await inkbox.createIdentity("sales-bot", {
  displayName: "Sales Bot",
  description: "Sales-outreach agent owned by the GTM team.",
  tunnel: { tlsMode: "edge" },
  phoneNumber: { type: "local" },
});
console.log(identity.mailbox!.emailAddress);  // e.g. sales-bot@inkboxmail.com
console.log(identity.tunnel!.publicHost);     // e.g. sales-bot.inkboxwire.com
console.log(identity.tunnel!.zone);           // inkboxwire.com
console.log(identity.phoneNumber?.number);   // e.g. +14155550100

inkbox identity create sales-bot \
--display-name "Sales Bot" \
--description "Sales-outreach agent owned by the GTM team." \
--tls-mode edge \
--phone-type local

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(name=identity.agent_handle, forward_to=...); see the Tunnels capability guide for forwarding modes, in-process handlers, and Passthrough TLS for CSR signing.

Provisioning a phone number

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.

# Provision a new phone number and link it to an existing identity
phone = identity.provision_phone_number(type="local")
print(phone.number)

// Provision a new phone number and link it to an existing identity
const phone = await identity.provisionPhoneNumber({ type: "local" });
console.log(phone.number);

# Provisions a new phone number and links it
inkbox number provision --handle sales-bot

Retrieving identities

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.

# Get a single identity by handle
identity = inkbox.get_identity("sales-bot")

# Re-sync channel state from the API if you already have the object in memory
identity.refresh()

# List all identities in your org
all_identities = inkbox.list_identities()
for identity in all_identities:
    print(identity.agent_handle, identity.display_name)

// Get a single identity by handle
const identity = await inkbox.getIdentity("sales-bot");

// Re-sync channel state from the API if you already have the object in memory
await identity.refresh();

// List all identities in your org
const allIdentities = await inkbox.listIdentities();
for (const identity of allIdentities) {
  console.log(identity.agentHandle, identity.displayName);
}

# Get a single identity by handle
inkbox identity get sales-bot

# Re-fetch identity from the API
inkbox identity refresh sales-bot

# List all identities in your org
inkbox identity list

Agent discovery

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.

Managing over time

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.

# Update display name and description; clear the description with None
identity.update(display_name="Sales Bot v2", description=None)

# Rename the handle (the linked tunnel is renamed in the same transaction)
identity.update(new_handle="sales-bot-v2")

// Update display name and description; clear the description with null
await identity.update({ displayName: "Sales Bot v2", description: null });

// Rename the handle (the linked tunnel is renamed in the same transaction)
await identity.update({ newHandle: "sales-bot-v2" });

# Update display name and description
inkbox identity update sales-bot --display-name "Sales Bot v2" --description "Updated copy."

# Rename the handle
inkbox identity update sales-bot --new-handle sales-bot-v2

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.

# Releases the phone number back to the carrier; the identity stays active
identity.unlink_phone_number()

// Releases the phone number back to the carrier; the identity stays active
await identity.unlinkPhoneNumber();

# Phone-number release is available via the SDK or API

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.

identity.delete()

await identity.delete();

inkbox identity delete sales-bot

Get started

Capabilities

API keys

MCP

Webhooks

Signing keys

Skills

Integrations

Creating an identity

Provisioning a phone number

Retrieving identities

Agent discovery

Managing over time

​Creating an identity

​Provisioning a phone number

​Retrieving identities

​Agent discovery

​Managing over time

Creating an identity

Provisioning a phone number

Retrieving identities

Agent discovery

Managing over time