Skip to main content

Authentication

All authenticated requests carry Authorization: Bearer <token>.

People: the dashboard session​

Signing in to the dashboard issues a session token. It is what the browser sends, and it is what you use for scripts that act as you: reading the audit log, exporting posture, managing members.

Regular dashboard sign-in at /login is powered by Clerk. The Clerk component stays mounted throughout /login/*, including social-provider callbacks, email verification, and additional verification steps. Clerk tokens are verified by the backend through go-login against the configured CLERK_ISSUER_URL.

The separate /demo-login page accepts the dedicated demo account's email and password through POST /api/auth/login. It issues a local session token and does not require a Clerk session. The same API authentication and organization scoping apply. This is also the password path for configured self-hosted accounts.

The local development harness uses VITE_DEV_AUTH_BYPASS together with a server-side Vite proxy token. The client bypass is compiled out of production builds, and the proxy does not exist in the deployed app. Production demos use the authenticated demo sign-in instead.

Machines: the device-code flow​

An AgentShield installation never holds a person's password. agentshield login runs a device-code flow:

  1. POST /api/auth/device-code returns a short user code and a verification URL.
  2. The person opens the URL, signs in, and confirms the code (/api/auth/device-verify).
  3. The CLI polls POST /api/auth/device-token and receives an agent token scoped to that installation.

The agent token is used for heartbeats, policy pulls, rule-pack downloads and audit ingestion. Revoke it by removing the agent on the Agents page.

Two-factor authentication​

When an account has application TOTP enabled, the dashboard requires the additional verification step (/api/auth/2fa/verify). Trusted devices can be remembered. Clerk's configured verification steps also remain part of regular sign-in.

Public disposable demo​

POST /api/demo/session starts an isolated Northwind workspace and returns an opaque session handle. The demo client keeps it in tab-scoped sessionStorage and sends it as X-Demo-Session to /api/demo/*. It is not a JWT and grants no access to normal /api/* tenant routes. DELETE /api/demo/session destroys the workspace. Handles expire after one hour of inactivity or a server restart.

The demo API has an explicit route allowlist for exploring evidence and editing temporary organization/policy settings. AI provider keys, AI calls, account credentials, invitations, tokens, and external integrations are unavailable. The manager has no production database or provider configuration. Visitor changes are discarded when the session ends; selecting Reset demo starts from the original scenario.