Keys and credentials

Admin Key

An API key with Org scope (tigby_admin_…). Minted in the console, with POST /api/keys, or by tigby login; named, shown once, stored hashed. Wherever a console session is accepted, an Admin Key is too – except on the session endpoints themselves. Revoking one (DELETE /api/keys/{id} in the reference, tigby key revoke in the CLI) takes effect on the next request: 401 api_key_invalid.

Identity Key

An API key scoped to a single Identity (tigby_id_…). The first one is minted by the last step of provisioning and handed over exactly once, by GET /api/identities/{handle}/identity-key – not by the status read, which carries no credential in any state. An Identity Key may act as its own Identity; on another Identity it is refused with 403 identity_scope_mismatch, and on Org-level endpoints with 403 admin_scope_required. All of an Identity's keys are revoked as the first act of its teardown.

Give the agent an Identity Key, keep the Admin Key for yourself: the agent can then read its mail, run its Tunnel, and post through its Connectors, but cannot create Identities, change the allowlist, or touch billing.

Sessions and magic links

The console signs in with a magic link – a one-time, 15-minute link mailed on signup and on every later sign-in; there is no password. Consuming it mints a server-side session carried in an httpOnly cookie. Sessions expire after 30 days and are revocable.

Errors

Every refusal is an RFC 9457 problem document with three Tigby members on top:

• code – stable, part of the contract; branch on this.
• agent_hint – what to do next: fix the call, wait, or stop.
• doc_url – where a human reads more.

title and detail are prose and may change; the code does not. Both SDKs raise this shape as TigbyError, and the MCP server returns it in structuredContent.