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:
- Bootstrap admin key: one organization, simplest setup.
- User registration: many organizations, each with its own users.
Access scope at a glance
Section titled “Access scope at a glance”Every request resolves to one of six credential types. Each type gives access to a different part of the API:
| Credential | Org-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 true | Can 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:
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_allowlistentry is an IP address ("203.0.113.5", treated as/32) or a CIDR block ("203.0.113.0/24"). - Omit
ip_allowlist, or sendnull, 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-Foraddress, not the proxy’s address.
See Service accounts for the full IP-matching rules.
Send the key with each request:
curl -H "X-API-Key: xK9mZ..." http://localhost:8000/v1/packsHuman 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:
curl -X POST http://localhost:8000/v1/auth/register \ -H "Content-Type: application/json" \# → 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_tokeninstead oforg_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.
membercan run the full analysis workflow: rules, ingest, analyze, and findings triage.adminorowneris required for org settings: service accounts, invitation links, LLM credentials, quota, pack load and unload, and the GitHub App integration.auditorsits 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.pipelinesits 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/meandGET /v1/auth/me/organizationsreturn the current user and their orgs from the session cookie. The dashboard calls them on page load.POST /v1/auth/session/switchscopes the session cookie to another org the user belongs to.
Profile and password
Section titled “Profile and password”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.
Your data
Section titled “Your data”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.
Session lifetime and revocation
Section titled “Session lifetime and revocation”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:
| Action | Endpoint |
|---|---|
| Account deactivated platform-wide | PATCH /v1/admin/users/{user_id} with is_active: false |
| Password reset by an admin | POST /v1/admin/users/{user_id}/reset-password, POST /v1/orgs/{org_id}/members/{user_id}/reset-password |
| Two-factor reset by an admin | POST /v1/admin/users/{user_id}/2fa-reset, POST /v1/orgs/{org_id}/members/{user_id}/reset-2fa |
| Platform-admin rights granted or revoked | POST /v1/admin/users/{user_id}/superadmin |
| Password changed by the user | POST /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.
Two-factor authentication
Section titled “Two-factor authentication”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.
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:
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.
Choosing how members sign in
Section titled “Choosing how members sign in”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:
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.
Next: SSO and SCIM
Section titled “Next: SSO and SCIM”To let an organization’s identity provider (Entra ID, Okta, Google, …) handle login or user provisioning, see Quick Start: SSO & SCIM.