Skip to content
Andy Developer Docs
Esc
↑↓navigate↵open⌘Jpreview
On this page

Authentication

Sign in, operate scoped Workspace API Keys, and recover safely.

Sign in

Outcome: establish a supported User session and select the intended Workspace.

Prerequisites: complete first-time sign-up and any required User setup in the Andy App.

andy auth login
andy auth status --json
andy workspace list --json
andy workspace select --workspace <workspace-id-or-slug>

Interactive login uses Clerk-hosted OAuth Authorization Code with S256 PKCE. The CLI stores the User session in the operating-system credential store when available. Workspace selection is explicit: --workspace, then the current profile, then a sole available Workspace, then an interactive prompt. Ambiguous non-interactive requests fail closed.

API Keys

Outcome: give unattended automation least-privilege access to one Workspace.

Prerequisites: only a current Workspace Admin using an interactive User credential can create, rotate, or revoke Workspace API Keys.

andy api-key create --workspace <workspace-id> --name "Knowledge sync" --scopes workspace:read,agent:read,knowledge_source:read,knowledge_source:write --save-as knowledge-sync --json
andy profile select --name knowledge-sync
andy auth status --json
andy api-key rotate --workspace <workspace-id> --key <key-id> --save-as knowledge-sync-next --json
andy api-key revoke --workspace <workspace-id> --key <old-key-id> --yes --json

Keys are bound to one Workspace. Prefer the operating-system credential store or a secret manager. ANDY_API_KEY is supported for unattended execution. Rotation leaves the previous key active until you verify the replacement and explicitly revoke it. Never commit a key or include it in logs or JSON evidence.

Problems and recovery

  • Exit 3 means authentication, reauthentication, or first-time User setup is required.
  • Exit 4 means a stable authorization, role, scope, Entitlement, archived-Workspace, resource, or conflict problem.
  • A revoked or expired User session requires andy auth login again.
  • A revoked Workspace key must be replaced by a Workspace Admin; it cannot refresh itself.
  • Entitlement loss and archived Workspaces fail closed. Authentication never widens product authority.

Machine-readable verification: run andy auth status --json; require status to be ready, inspect auth.mode, workspace.id, and credential.scopes, and preserve meta.requestId on failure.

Next step: continue with Workspaces and Agents. The retired user-scoped key is not accepted, and no legacy credential or raw backend configuration is imported.

Was this page helpful?