Org, Identity, Handle

Org

The customer as a whole. An Org owns Identities, the Vault, API keys and billing, and carries the language the console and transactional mail speak. It is implicit in every API call through the credential – never part of a URL.

Identity

The core resource: one agent's addressable presence. An Identity atomically owns a Handle, a Mailbox, an A2A Card, and a Tunnel – they are provisioned together and torn down together. Its status is the state of that provisioning: provisioning, ready, failed, or deleting. A failed Identity stays visible with its checklist; POST /api/identities/orderbot/retry resumes the run.

Handle

The unique name of an Identity (@orderbot), fixed at creation. It doubles as the mailbox local part orderbot@tigby.eu, the profile path tigby.eu/@orderbot, and the Tunnel hostname orderbot.tigbywire.eu.

• a–z, 0–9 and hyphen, 3–63 characters, a valid DNS label. Hyphens do not count towards the three: a-b is refused, because the name it would claim is ab.
• Compared case-insensitively with hyphens stripped: order-bot and orderbot are one name.
• Unique across every Org and for all time: a deleted Identity's Handle is never reissued, because it was a receiving mail address on the brand domain. Every create is therefore a permanent claim, and an Org has a lifetime quota of Identities – deleted ones included.

GET /api/handles/orderbot is the live check: whether the name can be registered, and if not, why – taken, reserved, or invalid.

Reserved Handles

Part of the namespace is reserved: role addresses, infrastructure names, anything containing the brand, the example Handles used in marketing, and third-party brands that would be credible in an agent context. Tigby assigns a reserved name only to a rights holder it has verified through support; there is no self-service path.

The provisioning saga

Creating an Identity is asynchronous: reserve the Handle, then Mailbox, Tunnel, A2A Card, and the first Identity Key, one step at a time, retried with backoff. GET /api/identities/orderbot shows the per-step checklist while it runs. Deletion is the same run in reverse, after every key of the Identity has been revoked.