Authentication

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: a current Workspace Admin creates, rotates and revokes Workspace API Keys in the Andy App, under Ajustes → API Keys. The App shows the secret once.

pbpaste | andy auth login --with-key --profile knowledge-sync
andy profile select --name knowledge-sync
andy auth status --json
andy api-key list --workspace <workspace-id> --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. To rotate, create the replacement in the App, store it with andy auth login --with-key, verify it, then revoke the old key in the App. 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.