API keys

Long-lived API keys for headless agents and CI pipelines.

API keys are for machines that can't open a browser: CI runners, your backend, a sandbox VM template. artifacts login authenticates by bouncing through a browser; an API key is a long-lived tbo_* string you mint once in your User Center account and export on the host instead, so no login step ever runs there.

Skip this page if you only mount from machines where artifacts login works; interactive hosts don't need API keys.

Mint

API keys are issued by User Center, not the CLI. Sign in to your account dashboard at https://user.tonbo.dev, open the API keys section, and create a key. The value is shown once:

tbo_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Save it in your secret store (Fly secrets, GitHub Actions secrets, AWS SecretsManager, 1Password, etc.).

Use

Export the key in the headless environment. Both the CLI and the SDK auto-detect it, so there is no artifacts login step:

export TONBO_API_KEY=tbo_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

artifacts mount my-workspace /mnt/work

Any command the CLI runs while TONBO_API_KEY is set authenticates with that key. The orchestrator accepts both a browser-issued JWT and a tbo_* API key as the bearer.

Scope and permissions

An API key authenticates as your account, so it reaches the workspaces your account owns. Access is enforced by the Orchestrator on workspace ownership, not via OAuth scopes (Supabase issues only standard OIDC scopes). Mount mode (ro / rw) is chosen per mount, not baked into the key. Per-key workspace or mode scoping is not in v0; reach out if you need it.

Revoking a key does NOT terminate any mount sessions that the key had already issued. Mount sessions outlive their issuing token by design; the per-mount metadata-service permissions hold independently. To force-tear an in-flight mount, the customer has to artifacts unmount or you can delete the workspace.

Rotation

Mint a new key in User Center, deploy it to your CI / secret store, then revoke the old one. There's no built-in rolling-rotation; the same pattern as AWS access keys works fine.