Authentication

Browser and CLI authority

Browser sign-in creates a seven-day permit for account access. A passkey approval authorizes the selected wallet or exchange account for one hour by default, with an explicit 24-hour option. Each transaction still requires confirmation, but later confirmations reuse that authority without another passkey or extending its expiry. The same HttpOnly cookie carries account access and the expiring signing capability; switching wallets requires fresh authorization. This authority allows spending the selected wallet or account’s full balance. Logout and Stop do not invalidate a copied permit. Adding or removing a passkey requires separate passkey-management approval. CLI login authorizes account access and wildcard wallet.sign for hosted wallets and connected trading accounts. Agent starts use wallet-scoped delegations. Permits are valid until expiry or issuing-passkey deletion; signing out does not revoke a copied permit.

circuit auth login

The CLI creates an auth handoff ID and opens the browser. Sign in or create an account, then confirm the separate CLI authorization with your passkey. The CLI polls for the delivered permit for up to 300 seconds and stores it in ~/.circuit/auth.toml under the selected environment:

[production]
permit = "circuit_permit_<payload_b64u>.<proof_b64u>"

[staging]
permit = "..."

Requests send Authorization: Bearer <permit>. The API resolves the owned wallet or exchange credential covered by the permit, including private reads. KMS-T accounts also authorize their wallet-manager signing credential during handoff; this does not create a second client execution token. circuit auth login --local authorizes local signing. Local circuit run and circuit unwind verify a permit signed by the local identity created on the first circuit wallet add. The identity lives under ~/.circuit/local/; the permit is stored at ~/.circuit/local/permit. This works offline without a browser or Circuit account. Missing or expired permits require another local login; unattended runs use the cached permit until it expires. Local wallet add, list, delete and export use the local identity without a session permit. Hosted commands such as circuit upload and circuit run --hosted use browser-authorized CLI login.

Inspect and sign out

Command	Behavior
`circuit auth whoami`	Shows `username`, active `environment`, resolved `api`, credential `source` (auth file or `CIRCUIT_TOKEN`), and the decoded permit payload (`issuedAt`, `expiresAt`, `capabilities`). `--json` serializes the same fields. Never prints the raw token.
`circuit auth logout`	Removes only the selected environment’s auth-file section; deletes the file when no sections remain. Takes no parameters.
`circuit auth token`	Prints only the bearer wire string, suitable for capture into `CIRCUIT_TOKEN`.
`circuit auth token --json`	Prints `{ "token": "circuit_permit_..." }`.
`circuit auth token --decode`	Prints both decoded segments: payload and proof, without reshaping or verifying the passkey signature. Combine with `--json` for one JSON document.

Account-backed commands select the environment through --env or CIRCUIT_ENV and default to production. Use whoami to inspect authority and token when a script needs the actual credential.

Getting Started

Core Concepts

Examples

CLI Reference

SDK Reference

Advanced

Browser and CLI authority

Inspect and sign out

​Browser and CLI authority

​Sign in

​Local sign-in

​Inspect and sign out

Browser and CLI authority

Sign in

Local sign-in

Inspect and sign out