Login

A locally trusted instance (vagaris onboard --yes) needs no credential: the CLI talks to http://localhost:3100 and the server accepts it. Everything on this page applies once an instance runs in an authenticated mode — --bind lan, --bind tailnet, or any deployed server.

Board login

vagaris auth login

What happens, in order:

1. The CLI fetches the instance's identity configuration from GET /api/cli-auth/oidc-config and runs OpenID Connect discovery against the issuer it names.
2. It starts a loopback callback listener and opens an authorization URL in your browser (authorization code flow with PKCE, prompt=consent so a refresh token is granted). The URL is also printed on stderr in case the browser does not open.
3. After you sign in, the callback receives the code, the CLI exchanges it for tokens and calls GET /api/cli-auth/me to confirm the identity.
4. The credential is stored for this API base. The access and refresh tokens go into the OS credential store — macOS Keychain via security, Linux Secret Service via secret-tool; ~/.vagris/auth.json holds only metadata. If no credential store is available, login still succeeds for the current command but is not persisted, and the CLI says so.

For a canonical platform/operator identity, use the explicitly configured operator entry:

vagaris auth login --operator

The server must set IDENTITY_OPERATOR_CLI_CLIENT_ID to its registered operator native client (the first-party client is app-vagaris-operator-cli). This selects the existing platform population; it does not create a new admin identity, link accounts by email, or grant organization/instance permissions. Without this configuration the request refuses rather than silently sending the operator to customer login. Ordinary auth login keeps the customer entry. Stored operator mode survives refresh and automatic reauthentication.

Authentication and local authorization are separate: linked: false means the identity authenticated but has no explicit link to a local board user. An already-authorized instance administrator must establish that immutable-subject link through the existing user-management API. Repeated password attempts or a duplicate per-product admin account do not repair a missing link.

--instance-admin makes login fail unless the signed-in identity already holds instance-admin. Use it when you are about to run an admin-only command and want a clear error up front.

Output includes apiBase, userId, whether the identity is linked to a board user, and persisted.

Automatic recovery

You rarely need to run auth login by hand. When a client command gets a 401, or a 403 whose message says board access or instance-admin is required, and both stdin and stdout are terminals, the CLI first tries to refresh a stored OIDC credential and otherwise starts the login flow inline, then retries the request. In a non-interactive context (CI, piped output) no browser flow is attempted and the command exits with code 3.

Who am I

vagaris auth whoami

Returns the user record, instance roles, isInstanceAdmin, isOperator, the company ids the identity can see, the credential source, and linked.

Logout

vagaris auth logout

Revokes the stored credential server-side, then removes it locally. If the server-side revoke fails the local credential is still removed; the output reports both revoked and removedLocalCredential.

Browser operator sign-in

When enabled, the sign-in page separates Continue with Vagary Identity from Local instance account. Use your canonical platform account for the former; the local form uses credentials created on that instance. A private/incognito window is not required. An authenticated identity still needs an explicit, administrator-approved subject link; another account with the same email does not inherit access.

Deployment prerequisites:

• Set IDENTITY_OPERATOR_BROWSER_CLIENT_ID=app-vagary alongside the trusted issuer, JWKS URL, resource audience and canonical public base URL.
• Register the exact HTTPS callback /api/auth/oauth2/callback/vagary_identity on that platform browser client, not on a native loopback client.
• Configure the existing revocation feed URL/token. Operator sessions are refused until the feed has synchronized at least once.
• Apply the additive session-provenance migration before starting the new server.

Browser sign-in explicitly reauthenticates and verifies the issuer's auth_time and nonce. The server stores encrypted, session-bound proof and never exposes upstream tokens through the browser session API. Operator sessions expire no later than their verified token bounds; this first slice does not silently refresh them, so expiry requests another sign-in. Local password sessions retain their existing behavior. Sign-out ends the local session; it is not a fleet-wide logout.

Revocation uses the canonical verifier's known-revocation cache. After initial synchronization that cache retains its last-known state during feed outages; immediate fleet-wide revocation during an outage is not guaranteed. Token expiry and current local subject-link checks remain enforced.

API keys

An agent API key authenticates as an agent rather than as a board user. It is what vagaris heartbeat run, the MCP server and a local coding agent use.

• Create one for an agent with vagaris agent local-cli <agent> --company-id <id> — it prints shell export lines for the key, API base, company and agent ids. See Coding-Agent Integration.
• Pass it with --api-key <token>, or set VAGARIS_API_KEY (legacy PAPERCLIP_API_KEY).
• Prefer keeping it out of the context file: vagaris context set --api-key-env-var-name VAGARIS_API_KEY records the name of the variable, and the CLI reads the value from your environment at run time.

Credential precedence

For every client command the CLI resolves, in this order, and stops at the first hit:

Value	Order
API base	--api-base → VAGARIS_API_URL / PAPERCLIP_API_URL → profile apiBase → http://<VAGARIS_SERVER_HOST or localhost>:<VAGARIS_SERVER_PORT or config server.port or 3100>
Credential	--api-key → VAGARIS_API_KEY / PAPERCLIP_API_KEY → the env var named by the profile's apiKeyEnvVarName → the stored board credential for that API base
Company	--company-id → VAGARIS_COMPANY_ID / PAPERCLIP_COMPANY_ID → profile companyId

An explicit API key disables the automatic board-login recovery, so a script that sets VAGARIS_API_KEY never opens a browser.

First administrator on a fresh authenticated instance

When an instance starts in authenticated mode there is no user yet. vagaris run generates a one-time bootstrap invite automatically when the database is the embedded one; for an external database create it yourself:

vagaris auth bootstrap-ceo --expires-hours 24 --base-url https://vagaris.example.com

It prints an invite URL. Open it in a browser to create the first instance admin. --force mints a new invite even if an admin already exists. See Enterprise Deployment.