Authentication

Browser and CLI authority

Browser sign-in creates a seven-day permit for account access. A passkey approval authorizes the selected wallet or Kraken account for one hour. 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 Kraken account’s full balance. Signing out and Stop do not invalidate a copied permit. Adding or removing a passkey requires separate passkey-management approval. CLI sign-in authorizes account access only. An operation approval opens a separate passkey handoff for the selected wallet’s 24-hour signing authority, which the CLI stores and reuses for later approvals. Agent starts open a separate handoff for 30 days of authority over exactly the selected wallet and explicitly attached exchange credentials; renew it, or restore invalid or expired authorization, with circuit auth agent <session-id> or Renew authorization in the agent menu. A session’s stored permit never leaves Circuit, so resuming a --target hosted-engine session opens the same handoff again. Renewal preserves the original wallet and exchange permissions by default; explicitly supplied broader permits remain accepted. Each handoff permit is encrypted to a one-time key held by the waiting CLI. Agent code never receives the session permit: the runtime adds it to engine requests on the agent’s behalf. circuit auth logout revokes the CLI permit, and renewing a session revokes the permit it replaces.

circuit auth login

The CLI prints an authorization link to stderr, including with --json, and opens it in the browser. Sign in or create an account, then review the recorded permissions and approve with your passkey. Never approve a link someone else sent you. Only the CLI holding its separate polling secret can collect the permit; it waits up to 300 seconds and stores the permit in ~/.circuit/auth.toml under the selected environment:

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

[staging]
permit = "..."

circuit auth login reuses a stored permit the API still accepts; --force skips that check and signs in again, and fails while CIRCUIT_TOKEN is set. Requests send Authorization: Bearer <permit>. The API resolves the owned wallet or exchange credential covered by the permit, including private reads. For headless starts and approvals, provide an independently passkey-signed CIRCUIT_SIGNING_PERMIT alongside your account CIRCUIT_TOKEN. The supplied permit must name the session wallet and attachments; Circuit rejects signing permits that use the * wallet wildcard. A new account-only sign-in cannot authorize agent signing. auth.toml sections accept only a nonempty permit field; malformed or unknown fields fail explicitly.

Local signing

Local circuit run needs no sign-in: unlocking the local keystore with the identity under ~/.circuit/local/ authorizes signing. It works offline without a browser or Circuit account.

Inspect and sign out

Command	Behavior
`circuit auth whoami`	Shows `username`, active `environment`, resolved `controlPlane`, 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. In CI, set `CIRCUIT_TOKEN` to it; it takes precedence over the auth file and bypasses browser sign-in.
`circuit auth token --json`	Prints `{ "token": "circuit_permit_..." }`.
`circuit auth token --decode`	Prints both decoded segments: payload and proof, after validating the permit envelope, without verifying the passkey signature. Combine with `--json` for one JSON document.

Getting Started

CLI Reference

SDK Reference

Browser and CLI authority

Local signing

Inspect and sign out

​Browser and CLI authority

​Sign in

​Local signing

​Inspect and sign out

Browser and CLI authority

Sign in

Local signing

Inspect and sign out