Skip to content
DashboardWebsite

Quick Start: Authentication

Just want to do it in the dashboard? See the guide: Decide who can sign up and how people sign in or Create a service account for CI.

By default, authentication is disabled. Every request uses the anonymous owner of the default organization, with platform-admin access. To enable authentication, choose a bootstrap admin key for a single organization or user registration for multiple organizations:

Every request resolves to one of six credential types. Each type gives access to a different part of the API:

CredentialOrg-scoped endpoints (/orgs/*, rules, findings, …)/admin/* (cross-tenant)POST /v1/orgs / POST /v1/auth/register with org_name (create an org)Notes
Anonymous (auth.api_key: null)✅ as owner of the default org✅ (auto-superadmin)❌Every request resolves to the same principal. Use for local development only
Bootstrap key (config.auth.api_key, sent as X-API-Key)✅ as owner of the default org✅ (auto-superadmin)❌Root-equivalent in default and for every org’s admin data. It has no user_id, so it cannot call endpoints that require a logged-in user
Service-account API key (POST /v1/auth/keys, X-API-Key)✅ scoped to the org it was created in, at its assigned OrgRole❌❌The standard machine-to-machine credential: CI, MCP clients, most Terraform provider resources
Access token (POST /v1/auth/me/access-tokens, Authorization: Bearer ot_pat_…)✅ as the person who created it, in one of their orgs, capped by the token’s scope✅ only for a superadmin’s admin token❌For an agent or a script acting as you. See Access Tokens for Agents
Human session — ordinary member✅ scoped to whichever org the session is currently switched to, at that OrgRole❌Only if registration.allow_public_org_creation is trueCan belong to several orgs. POST /v1/auth/session/switch changes the active org
Human session — superadmin (is_superadmin: true)✅ same as above, for orgs they belong to✅✅ always (the setting does not apply)Has cross-tenant admin access. See Platform Admin

OrgRole (viewer < member < admin < owner) and is_superadmin are independent. A role in an org does not grant access across orgs. Cross-org access does not grant a role in an org.

To view an org they are not a member of, a superadmin uses GET /v1/admin/organizations/{org_id}. GET /v1/orgs/{org_id} returns 404 unless the session is scoped to that org. See Platform Admin for the full is_superadmin reference.

Bootstrap admin key (single org, simplest)

Section titled “Bootstrap admin key (single org, simplest)”
auth:
api_key: "change-me-to-a-strong-secret"

This key is the permanent owner of the default org. For CI pipelines, create service accounts. A service account is a named key with a role. You can restrict it to a set of source IPs. In the dashboard: Organization → Access → Service Accounts. Or through the API:

Terminal window
curl -X POST http://localhost:8000/v1/auth/keys \
-H "X-API-Key: change-me-to-a-strong-secret" \
-H "Content-Type: application/json" \
-d '{"role": "pipeline", "name": "ci-pipeline", "ip_allowlist": ["203.0.113.0/24"]}'

role, name and ip_allowlist are optional. role defaults to pipeline, the narrowest role that runs analyses.

  • Each ip_allowlist entry is an IP address ("203.0.113.5", treated as /32) or a CIDR block ("203.0.113.0/24").
  • Omit ip_allowlist, or send null, to allow the key from any address.
  • A request from outside the allowlist gets 403. The key is valid but not allowed from that address. An unknown or revoked key gets 401.
  • Behind a reverse proxy, the server checks the leftmost X-Forwarded-For address, not the proxy’s address.

See Service accounts for the full IP-matching rules.

Send the key with each request:

Terminal window
curl -H "X-API-Key: xK9mZ..." http://localhost:8000/v1/packs

Human registration (multi-tenant, real orgs)

Section titled “Human registration (multi-tenant, real orgs)”

Use registration for a multi-tenant deployment, where several independent teams each have their own org. Users register directly. They do not use the bootstrap key:

Terminal window
curl -X POST http://localhost:8000/v1/auth/register \
-H "Content-Type: application/json" \
-d '{"email": "[email protected]", "password": "at-least-8-chars", "org_name": "My Org"}'
# → sets a session cookie. You are now the "owner" of a new organization.

Every later request from this session is scoped to the new org. API keys created in the org are scoped to it too. Other orgs cannot see its resources, findings, or billing.

org_name is optional. You can also register in two other ways:

  • Join an existing org with an invitation link. Send invite_token instead of org_name. You join that org with the role that the link grants. See Invitations to create a link.
  • Register without an org. Send neither field. The account can sign in, but every org-scoped endpoint returns 403. The user must create an org (POST /v1/orgs) or accept an invitation first. The dashboard shows this as “signed in, but not part of an organization yet”.

Roles use the same hierarchy for API keys and user memberships: viewer < member < admin < owner.

  • member can run the full analysis workflow: rules, ingest, analyze, and findings triage.
  • admin or owner is required for org settings: service accounts, invitation links, LLM credentials, quota, pack load and unload, and the GitHub App integration.
  • auditor sits off the ladder. It reads everything, including the audit log and telemetry, and changes nothing. Give it to a security team or to the API key of a SIEM collector. See Roles.
  • pipeline sits off the ladder too, and only an API key can hold it. It runs analyses (rules, ingest, analyze, submit findings, report, jobs) and nothing else: no triage, no rules editing, no settings. Use it for CI jobs and for agents on the MCP service.

Each endpoint requires a named permission, such as members:manage or analysis:run. A role holds every permission whose default role is the same or lower. A 403 response names the missing permission. GET /v1/permissions lists every permission with its default role. GET /v1/auth/me returns the permissions the caller holds.

A signed-in user can belong to several orgs.

  • GET /v1/auth/me and GET /v1/auth/me/organizations return the current user and their orgs from the session cookie. The dashboard calls them on page load.
  • POST /v1/auth/session/switch scopes the session cookie to another org the user belongs to.

Users set their display name and change their password on the dashboard’s Account page, on the Profile and Sign-in tabs. The API endpoints are PATCH /v1/auth/me and POST /v1/auth/me/password. See API Reference — Session. Changing a password requires the current password.

  • Forgotten password. The user requests a reset link from the login page (POST /v1/auth/password/forgot). They set a new password from the emailed link (POST /v1/auth/password/reset). See Email.
  • Reset by an admin. An org admin or platform admin can reset another user’s password. The password is cleared and the user receives the same kind of link. The response also returns the link once, for deployments that do not send email. See Members and Platform Admin — Managing members.

These options do not apply to accounts created through SSO or a sign-in provider (auth_provider != "local"). These accounts have no local password. GET /v1/auth/me reports has_password: false, and the Account page hides the password options.

Changing a password signs the account out everywhere else. Every other browser and device is rejected on its next request. The browser that made the change stays signed in with a new cookie from the response.

This is intentional. Users often change their password because someone else may have access to the account. An active session does not re-check the password by itself.

On the Account page’s Your data tab, users download everything the platform holds about them, or delete their account. An organization’s only owner first chooses who takes each such organization over, or locks it. See DELETE /v1/auth/me.

A session cookie is a signed JWT. It is valid for session.access_ttl_minutes (default 480, eight hours). You can change the value with PATCH /v1/admin/settings.

The TTL is the maximum session length. A revoked session stops working immediately, before the TTL ends. On every request, the server re-reads the account and returns 401 if:

  • the account has been deactivated, or
  • the account’s sessions were revoked after the cookie was issued.

The dashboard handles this 401 like any other and redirects to the login page.

These actions revoke every session of an account:

ActionEndpoint
Account deactivated platform-widePATCH /v1/admin/users/{user_id} with is_active: false
Password reset by an adminPOST /v1/admin/users/{user_id}/reset-password, POST /v1/orgs/{org_id}/members/{user_id}/reset-password
Two-factor reset by an adminPOST /v1/admin/users/{user_id}/2fa-reset, POST /v1/orgs/{org_id}/members/{user_id}/reset-2fa
Platform-admin rights granted or revokedPOST /v1/admin/users/{user_id}/superadmin
Password changed by the userPOST /v1/auth/me/password — every session except the caller’s own

A deactivated account cannot sign in again by password, SSO, or a sign-in provider.

Users with a local (email and password) account can enable TOTP two-factor authentication on the dashboard’s Account page, Sign-in tab. Any RFC 6238 app works, such as Google Authenticator, Authy, or 1Password. Accounts that use SSO cannot enable TOTP, because they have no local password.

Terminal window
curl -X POST http://localhost:8000/v1/auth/me/2fa/enroll \
-H "Cookie: mcp_session=..."
# → {"secret_provisioning_uri": "otpauth://...", "manual_entry_code": "JBSW..."}
# scan the URI as a QR code, or enter manual_entry_code by hand, then:
curl -X POST http://localhost:8000/v1/auth/me/2fa/confirm \
-H "Cookie: mcp_session=..." -H "Content-Type: application/json" \
-d '{"code": "123456"}'
# → {"recovery_codes": ["a1b2c3...", ...]}
# 10 one-time codes. They are shown once. Store them safely.

2FA is active only after confirm succeeds. A secret from enroll alone is pending and not enforced.

When 2FA is enabled, POST /v1/auth/session does not set a session cookie. It returns {"mfa_token": "...", "methods": [...]}. Send the token with a code in a second call:

Terminal window
curl -X POST http://localhost:8000/v1/auth/session/2fa \
-H "Content-Type: application/json" \
-d '{"mfa_token": "...", "code": "123456"}'
# → same response as a normal login. The session cookie is set.

The server checks code as a TOTP code first, then as an unused recovery code. Either one completes the login. Each recovery code works once. To get new codes, disable 2FA and enroll again. POST /v1/auth/me/2fa/disable requires the current password.

Lost device and recovery codes. An org admin or platform superadmin can reset a member’s 2FA on the dashboard’s Members page. The API endpoints are POST /v1/orgs/{org_id}/members/{user_id}/reset-2fa and POST /v1/admin/organizations/{org_id}/members/{user_id}/reset-2fa. The reset clears the enrollment, and the member can enroll again. See Platform Admin — Managing members.

An org admin chooses which sign-in methods the organization accepts: password, SSO, and social (Google or Microsoft). All three are accepted by default. Set them on the dashboard’s SSO page, under Sign-in methods, or with the API:

Terminal window
curl -X PUT http://localhost:8000/v1/orgs/{org_id}/sign-in-methods \
-H "Content-Type: application/json" -b cookies.txt \
-d '{"allowed": ["password", "sso"]}'
  • A member whose session came from another method gets 403 on every org-scoped page and API call, with the accepted methods in the message. They sign out and sign in another way.
  • The method is the one the member signed in with. Switching orgs keeps it.
  • Service account API keys are not affected.
  • The server refuses a list that would refuse your own session, and SSO alone while the organization has no enabled SSO connection. Either would leave nobody able to change it back.

To let an organization’s identity provider (Entra ID, Okta, Google, …) handle login or user provisioning, see Quick Start: SSO & SCIM.