levelrail-cli auth-engine status (root only) or on Settings > Security. It reports the library version and whether two-factor, passkeys and OAuth are available.
Requirements
Settings
All optional.Upgrading from a release before the auth library
The auth library replaced the old built-in sign-in, and that change breaks existing installs (the platform had no production users when it landed). After upgrading fromv0.2.0-beta.18 or earlier:
- Everyone is signed out. Sign in again with your existing username and password: accounts and password hashes carry over.
- API tokens created before the upgrade stop working (they answer 401). Create new ones in Settings, CLI Access, or run
levelrail-cli auth login --device, and update CI secrets. - Two-factor codes, passkeys and recovery codes are not carried over. Re-enroll them after signing in.
levelrail restore-db.
Things to know
- API tokens carry the
tk_style prefix of the product. A token’s effective abilities never exceed its owner’s current abilities. - A TOTP code can be used once. Repeated wrong codes lock the user out, counted across devices, and answer 429 with
Retry-After. - Recovery codes look like
XXXX-XXXX-XXXX-XXXXand are accepted with or without hyphens and in any case. - Sign-in is case-insensitive on the username. Usernames that are not an email address (for example
admin) are still accepted at first-run and by invites. - OAuth callback URL: register
https://<your-host>/api/v1/auth/oauth/<provider>/callbackat each identity provider. Sign-in and profile linking share it, and Levelrail tells them apart by the state value. Once a dashboard URL is set, redirect hosts are limited to it and the base URL host, plus any inAPP_AUTH_ENGINE_OAUTH_ALLOWED_HOSTS. The redirect URI is always built from the dashboard URL (orAPP_DASHBOARD_URL). With neither set, the request’sHostandX-Forwarded-Protoare used only from a loopback peer or one listed inAPP_INGRESS_TRUSTED_PROXIES; any other caller gets a400until a dashboard URL is set. - An existing account is linked on OAuth sign-in only when the provider reports the email as verified. A provider’s allowed email domain gates new accounts only.
recover-adminsets the password through the library, which also ends that account’s sessions and clears its lockout. No restart is needed. Locked out another way? See Emergency access.
Troubleshooting
Passkeys not available, getting “Passkey registration is not available”
Likely cause: The control plane is running on an IP address instead of a domain name, orAPP_AUTH_ENGINE_WEBAUTHN_RP_ID is not set.
How to confirm: Run levelrail-cli auth-engine status and check the “Passkeys” line. If it says “not available”, passkeys are disabled. Check what URL is set: Dashboard Settings > Security or run curl https://<control-plane-url>/api/v1/brand.
Fix: Set your dashboard to a domain name (not an IP), or set APP_AUTH_ENGINE_WEBAUTHN_RP_ID to your domain and restart the control plane.
Still stuck: See Configuration for how to set environment variables and restart.
Two-factor codes not working or “Enrollment unavailable”
Likely cause: The master key is not configured. Two-factor, passkeys and OAuth all need the control plane’s encryption master key to function. How to confirm: Runlevelrail-cli auth-engine status and check whether “2FA” and “OAuth” are available. Both should show “available (requires master key)”. If the master key is missing, they will show “not available”.
Fix: Set APP_MASTER_KEY to the master key value and restart the control plane. See Master key rotation for how to set or recover the master key.
Still stuck: Read Master key if you lost the master key.
OAuth callback failing with “redirect_uri_mismatch”
Likely cause: The OAuth redirect URI registered at the provider does not match what the control plane is sending. The platform builds the URI from the dashboard URL, and the host must match exactly (includingwww.).
How to confirm: Check your OAuth provider’s console for which URIs are registered. On the control plane, run curl https://<control-plane-url>/api/v1/brand and note the exact domain in “domain”. Register https://<that-domain>/api/v1/auth/oauth/<provider>/callback at the provider.
Fix: Update the registered redirect URI at your OAuth provider to exactly match https://<dashboard-domain>/api/v1/auth/oauth/<provider>/callback. If you need to use a different hostname, set APP_AUTH_ENGINE_OAUTH_ALLOWED_HOSTS to comma-separated allowed hosts.
Still stuck: See SSO and SAML for identity provider setup.
API token returns 401 “Unauthorized” after an upgrade
Likely cause: You upgraded from v0.2.0-beta.18 or earlier, and API tokens created before the upgrade are no longer valid (the auth library replaced the old sign-in system). How to confirm: Check when the token was created. If it was before the upgrade, it is obsolete. Runlevelrail-cli auth login --device to mint a new token.
Fix: Create a new API token in Settings > CLI Access (dashboard) or by running levelrail-cli auth login --device, then update your CI or scripts to use the new token.
Still stuck: See API reference for the API surface.