Authentication

Two separate things share a word here. People sign in to the dashboard with email or an identity provider. Machines authenticate to the REST API with an API key. They use different credentials and different code paths.

People: sign-inCopy Anchor Link

Configured in Admin → Settings → Authentication, or by environment variable.

Email codesCopy Anchor Link

With SMTP configured, users sign in with a one-time code sent to their address. This is the baseline and needs no external provider.

GitHub and GoogleCopy Anchor Link

GITHUB_CLIENT_ID=
GITHUB_CLIENT_SECRET=
GOOGLE_CLIENT_ID=
GOOGLE_CLIENT_SECRET=

Register the callback with the provider:

{APP_URL}/api/auth/callback/github
{APP_URL}/api/auth/callback/google

OIDC / SSOCopy Anchor Link

Any compliant provider — Okta, Auth0, Keycloak, Entra ID, Authentik.

OIDC_ISSUER=https://id.example.com
OIDC_CLIENT_ID=
OIDC_CLIENT_SECRET=
OIDC_SCOPES=openid email profile      # default
OIDC_BUTTON_LABEL=Sign in with Okta   # button text

Callback: {APP_URL}/api/auth/callback/sso

Open signupsCopy Anchor Link

ALLOW_SIGNUPS=false   # default

Leave this off for an internal instance and invite people instead. An instance reachable from the internet with signups on will collect accounts you did not intend.

Machines: API keysCopy Anchor Link

The REST API accepts either a session cookie or an API key:

x-api-key: apikee_<payload>.<signature>
x-tenant:  acme

When both are present the API key wins, so a request can never be authorised by one credential while carrying another.

x-tenant is required for session callers because project slugs are unique per workspace, not globally. API-key callers are already scoped to the team owning the key's client and do not need it.

See the REST API.

Instance administratorsCopy Anchor Link

An admin flag on a user account grants /admin — instance-wide settings for email, storage, sign-in, AI and licensing.

This is separate from workspace roles. Owning a workspace does not make you an instance admin, and an instance admin is not automatically a member of every workspace.

The account that runs first-run setup becomes the first administrator. ADMIN_EMAIL and ADMIN_PASSWORD seed one before that.