Authentication & SSO¶

DeltaLLM supports API authentication, browser-based admin sessions, invitation-based onboarding, password recovery, MFA, SSO, and RBAC.

Choose the Simplest Working Method¶

Need	Start with
Call the proxy API quickly	Master key
Give an app limited access	Virtual API key
Sign in to the Admin UI	Bootstrap admin account
Use company identity	SSO

Quick Success Path¶

Set a valid DELTALLM_MASTER_KEY
Start the gateway
Use the master key to make one successful API call
Create a scoped virtual API key for real applications
Add session login, MFA, or SSO only when you need them

Master Key¶

The master key is the fastest way to get started. It has full access to proxy and admin endpoints.

general_settings:
  master_key: os.environ/DELTALLM_MASTER_KEY

curl http://localhost:8000/v1/chat/completions \
  -H "Authorization: Bearer YOUR_MASTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-4o-mini", "messages": [{"role": "user", "content": "Hello"}]}'

Virtual API Keys¶

Virtual keys are the right choice for applications because they can be scoped and limited.

curl -X POST http://localhost:8000/ui/api/keys \
  -H "Authorization: Bearer YOUR_MASTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "key_name": "production-app",
    "team_id": "team-production",
    "max_budget": 50.00
  }'

Virtual keys can include:

spend limits
RPM and TPM limits
team or organization ownership

Runtime model and route-group access is governed separately through callable-target bindings and scope policies. Keys no longer carry model allowlists on the key record.

Rotation and Revocation¶

DeltaLLM stores virtual keys hashed in the database and caches auth lookups in Redis.

regenerate replaces the current key and invalidates the old cache entry
revoke removes the key and invalidates that cache entry
delete removes the key record and invalidates that cache entry

The Admin UI uses a secure deltallm_session cookie.

To create the first admin account, set:

general_settings:
  platform_bootstrap_admin_email: admin@example.com
  platform_bootstrap_admin_password: os.environ/ADMIN_PASSWORD

That bootstrap account is created automatically on first startup when both values are present.

POST /auth/internal/login

The login response sets the session cookie used by the UI.

Password Change¶

POST /auth/internal/change-password

Use this when an account is marked to change its password after first login.

Invitations and Password Recovery¶

DeltaLLM now supports email-first account lifecycle flows:

invite a user by email from People & Access
let new users activate their account from an invite link
let existing users reset their password from the login page

Invitations¶

Invitation acceptance uses a single-use token and applies organization and team access only when the invite is accepted.

GET  /auth/invitations/{token}
POST /auth/invitations/accept

Important behavior:

new accounts without any auth method must set a password during invite acceptance
SSO-only accounts can accept invites without creating a local password
accounts with MFA enabled accept the invitation first, then complete a normal login flow

Password Recovery¶

POST /auth/internal/forgot-password
GET  /auth/internal/reset-password/{token}
POST /auth/internal/reset-password

The forgot-password flow is intentionally non-enumerating: the API returns the same success response whether the account exists or not.

Note

Invitation and reset emails require general_settings.email_base_url to be set to an absolute http:// or https:// URL. DeltaLLM now refuses to enable email delivery without it.

Multi-Factor Authentication¶

DeltaLLM supports TOTP-based MFA for session logins.

POST /auth/mfa/enroll/start
POST /auth/mfa/enroll/confirm
Include mfa_code during /auth/internal/login

Verified Sessions¶

For session-authenticated admin access, DeltaLLM distinguishes between:

a valid browser session
an MFA-verified browser session

If an account has MFA enabled, admin UI access is blocked until the session completes:

POST /auth/mfa/verify

This also applies to SSO-created sessions when the account already has MFA enabled.

Single Sign-On¶

DeltaLLM supports:

Microsoft Entra
Google
Okta
generic OIDC

Minimal SSO Configuration¶

general_settings:
  enable_sso: true
  sso_provider: microsoft
  sso_client_id: os.environ/SSO_CLIENT_ID
  sso_client_secret: os.environ/SSO_CLIENT_SECRET
  sso_authorize_url: https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize
  sso_token_url: https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token
  sso_userinfo_url: https://graph.microsoft.com/oidc/userinfo
  sso_redirect_uri: https://your-domain.com/auth/callback

How the SSO Flow Works¶

The user starts login from the UI
DeltaLLM redirects to the identity provider
The provider redirects back to /auth/callback
DeltaLLM creates or updates the platform account and sets a session cookie

Note

SSO callback state is stored in Redis. If Redis is unavailable, DeltaLLM keeps SSO disabled instead of advertising a broken login flow.

Auto-Assign Platform Admins¶

Add emails to sso_admin_email_list to grant platform_admin on first SSO login.

Role-Based Access Control¶

DeltaLLM separates platform roles, organization roles, and team roles.

Platform Roles¶

Role	Meaning
`platform_admin`	Full platform access
`org_user`	Access limited to assigned organizations

Organization Roles¶

Role	Typical access
`org_owner`	Full organization control
`org_admin`	Manage teams, users, and keys
`org_billing`	Spend-focused visibility
`org_auditor`	Read-only operational visibility
`org_member`	Basic organization membership

Team Roles¶

Role	Typical access
`team_admin`	Manage the team and its keys
`team_developer`	Use and create keys, self-service key creation (`key.create_self`)
`team_viewer`	Read-only access

The team_developer role includes the key.create_self permission, which allows developers to create, regenerate, revoke, and delete their own API keys when the team has self-service enabled. See API Keys: Self-Service for details.

Important Note on `user_role`¶

deltallm_usertable.user_role is metadata for user profile types in the UI. It is not the main authorization source of truth.