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, connect to Slack workspaces, 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

To let senders with active exact bidirectional allows invite this identity into group conversations, enable Companion mode. It is a separate, off-by-default toggle. You can enable it during onboarding before adding rules or channel resources; actual use still requires readiness and a qualifying authenticated group message. 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. Choose the handle when you create the identity. The handle and tunnel name are fixed after creation, including when the identity uses a custom sending domain. An inkboxmail.com address is also fixed with its agent handle. Update the display name, description, iMessage reachability, or contact-rule filter modes. Use the display name to change how your agent is presented. 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)

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

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

Sending agent_handle in an identity PATCH body returns 422, even if it matches the current handle or is null. This also applies to identities with custom-domain mailboxes. The handle in the URL selects the identity; it does not change it. 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

Domain affiliation

An organization admin can select one verified domain for an agent. Affiliation visibility follows the agent’s public/private setting. Attaching a domain with valid proof to an already-public agent makes the affiliation public immediately. Private agents share it only with their organization and authorized A2A peers. The affiliation API returns the saved selection even when its proof has expired. Removing it stops assertions for that identity.

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

Domain affiliation

​Creating an identity

​Provisioning a phone number

​Retrieving identities

​Agent discovery

​Managing over time

​Domain affiliation

Creating an identity

Provisioning a phone number

Retrieving identities

Agent discovery

Managing over time

Domain affiliation