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 by GET /api/identities/{handle}/identity-key – not by the status read, which carries no credential in any state. That route answers with it on every call until POST /api/identities/{handle}/identity-key/ack says it arrived or its short window closes, because a dropped response must not destroy a key nobody can re-mint. 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.

Revoking an Identity Key by hand (DELETE /api/keys/{id}, tigby key revoke) also severs that Identity's live Tunnel: a control connection is authorized once, when the agent connects, so without the sever a leaked key would keep an inbound path into your machine open for as long as the agent stayed connected. Traffic in flight ends mid-request, and the agent does not come back – an Identity Key cannot be re-issued. A tunnel server that could not be reached is owed the sever and retried until it confirms; one that answers and refuses turns the call into a 500, and the key is revoked either way, so retry it.

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.