System Config Reference
System config is the runtime configuration stored by seamless-auth-api in the system_config
table.
Use it for auth behavior that operators may need to inspect or change, such as login methods, roles, token TTLs, WebAuthn relying-party settings, OAuth provider metadata, and lockout policy.
Do not store raw secrets in system config. Secrets belong in environment variables or a secret manager.
How System Config Is Loaded
Section titled “How System Config Is Loaded”At startup, seamless-auth-api bootstraps each known config key. This runs once per process
start, before the server accepts requests, so an env change takes effect on the next restart.
Each row’s updatedBy column decides whether the env var or the stored row wins. Bootstrap and
migrations write rows with updatedBy set to NULL. A write through the admin API sets
updatedBy to the caller’s user id (or the service client id), which marks the row as
admin-managed. The admin API writes are PATCH /system-config/admin and the
/system-config/oauth-providers create, update, and delete routes; the admin dashboard uses
them.
For each key:
- if a row exists and
updatedByis set, the API uses the row and ignores the env var - if a row exists,
updatedByisNULL, and the mapped env var is set, the API parses the env var; when the result differs from the stored value it logs a warning and overwrites the row with the env value - if a row exists and the mapped env var is unset or empty, the API uses the row
- if no row exists and the mapped env var is set, the API parses the env var and creates the row
- if no row exists and the key has a built-in default, the API creates the row with that default
- if no row exists, no env var is set, and no default exists, startup fails with
Missing required system config "<key>". Provide ENV <ENV_VAR> or seed system_config.
The resolved config is then validated, and startup fails with Invalid system configuration: and
the validation errors if it does not match the schema.
So env vars stay authoritative on every boot for any key nobody has changed through the admin API,
and an admin edit stays authoritative over the env var from then on. A value that parses to null
(MAX_CONCURRENT_SESSIONS=none) is stored as no row, so step 2 deletes the row instead of
updating it.
The overwrite in step 2 logs at warn from the bootstrapSystemConfig logger:
Overwriting system_config "login_methods" from env LOGIN_METHODS: the stored value differs and the row is not marked admin-managed (updatedBy IS NULL). If this value was changed through the admin console, that change is being reverted here.No warning is logged when the env value matches the stored value, or when the row is admin-managed.
| Goal | What to do |
|---|---|
| Keep a key driven by env | Set the env var and change the key only through env |
| Keep an admin edit | Change the key through the admin API or dashboard; direct SQL that leaves updatedBy NULL is reverted on the next boot when the env var is set |
| Hand an admin-managed key back to env | No API does this: run UPDATE system_config SET "updatedBy" = NULL WHERE key = '<key>'; (or delete the row) and restart |
| Stop env from touching a non-admin row | Unset the env var; the stored value is kept and the built-in default is not restored |
An empty env var counts as unset, so MAX_CONCURRENT_SESSIONS= leaves an existing row alone and,
with no row, falls back to the built-in default of no cap. To remove a stored cap from env, set
none, null, or unlimited; like any env value, that applies only while the row is not
admin-managed. frontend_url is not accepted by
PATCH /system-config/admin, so it cannot become admin-managed through the API and follows
FRONTEND_URL whenever that is set.
Routes
Section titled “Routes”Raw auth API routes:
| Method | Route | Required access |
|---|---|---|
GET |
/system-config/public |
None (public) |
GET |
/system-config/roles |
admin:read |
GET |
/system-config/admin |
admin:read |
PATCH |
/system-config/admin |
admin:write |
GET |
/system-config/oauth-providers |
admin:read |
POST |
/system-config/oauth-providers |
admin:write |
PATCH |
/system-config/oauth-providers/:id |
admin:write |
DELETE |
/system-config/oauth-providers/:id |
admin:write |
Every route except /system-config/public requires an access token, and the role check runs after
it. None of these routes require step-up authentication.
GET /system-config/public needs no session. It returns only the enabled login methods, so sign-in
screens can offer the methods the instance allows before anyone is signed in:
{ "loginMethods": ["passkey", "magic_link"]}The /system-config/oauth-providers routes list, add, update, and remove entries in
oauth_providers. A list returns { "providers": [...] }, a create returns 201 with
{ "provider": ... } (or 409 when the id already exists), an update returns
{ "provider": ... }, and a delete returns { "success": true, "id": "<id>" }.
Through the Express adapter, use:
/auth/system-config/public/auth/system-config/roles/auth/system-config/admin/auth/system-config/oauth-providers/auth/system-config/oauth-providers/:idSuccessful PATCH /system-config/admin updates return:
{ "success": true, "updatedKeys": ["login_methods"]}The auth API logs system config reads, updates, and validation errors as auth events.
Config Keys
Section titled “Config Keys”| Key | Env seed | Type | Purpose |
|---|---|---|---|
app_name |
APP_NAME |
string | Display name used in auth flows and TOTP issuer |
default_roles |
DEFAULT_ROLES |
string array | Roles assigned to new users |
available_roles |
AVAILABLE_ROLES |
string array | Roles allowed in the system |
login_methods |
LOGIN_METHODS |
login method array | Methods offered after login starts |
passkey_login_fallback_enabled |
PASSKEY_LOGIN_FALLBACK_ENABLED |
boolean | Whether fallback methods can appear with passkey login |
prompt_passkey_enrollment |
PROMPT_PASSKEY_ENROLLMENT |
boolean | Ask users with no passkey to enroll one after a code or magic-link sign-in |
phishing_resistant_only |
PHISHING_RESISTANT_ONLY |
boolean | Accept only passkeys to start a session |
oauth_providers |
OAUTH_PROVIDERS |
JSON array | OAuth provider metadata |
lockout_policy |
LOCKOUT_POLICY |
JSON object | Failed-login lockout policy |
authenticator_policy |
AUTHENTICATOR_POLICY |
JSON object | Which passkey authenticators may register, and how they are verified |
recovery_codes |
RECOVERY_CODES |
JSON object | Whether users can generate and redeem recovery codes (v0.20) |
account_recovery |
ACCOUNT_RECOVERY |
JSON object | Self-service account recovery and its delay (v0.20) |
access_token_ttl |
ACCESS_TOKEN_TTL |
duration | Access token and access cookie TTL |
refresh_token_ttl |
REFRESH_TOKEN_TTL |
duration | Refresh cookie TTL |
session_idle_ttl |
SESSION_IDLE_TTL |
duration | How long a session may go without a refresh |
max_concurrent_sessions |
MAX_CONCURRENT_SESSIONS |
positive integer or null |
Sessions one user may hold at once; null is no cap |
rate_limit |
RATE_LIMIT |
number | Request rate limit value |
delay_after |
DELAY_AFTER |
number | Slowdown threshold |
flow_rate_limits |
FLOW_RATE_LIMITS |
JSON object | Per-IP and per-identity limits on OTP, magic-link, and OAuth starts |
rpid |
RPID |
string | WebAuthn relying party ID |
origins |
ORIGINS |
URL array | WebAuthn allowed browser origins |
frontend_url |
FRONTEND_URL |
URL | Sign-in and magic-link base URL; else origins[0] |
magic_link_redirect_uris |
MAGIC_LINK_REDIRECT_URIS |
URL array | Exact-match magic-link destinations; empty falls back to origins |
Built-in defaults exist for:
| Key | Default |
|---|---|
login_methods |
["passkey", "magic_link"] |
oauth_providers |
[] |
passkey_login_fallback_enabled |
true |
prompt_passkey_enrollment |
false |
phishing_resistant_only |
false |
lockout_policy |
enabled, 10 failures, 15-minute window, 15-minute lockout |
authenticator_policy |
see Authenticator Policy |
recovery_codes |
{ "enabled": true, "requireAtEnrollment": false } |
account_recovery |
{ "enabled": false, "delay": "24h" } (delay from 1h to 30d) |
session_idle_ttl |
"8h" |
max_concurrent_sessions |
null (no cap) |
flow_rate_limits |
see Flow Rate Limits |
magic_link_redirect_uris |
[] |
Other keys must come from env or an existing database row.
Env Parsing Rules
Section titled “Env Parsing Rules”| Env value | Parsing rule |
|---|---|
DEFAULT_ROLES |
Comma-separated list |
AVAILABLE_ROLES |
Comma-separated list |
LOGIN_METHODS |
Comma-separated list |
ORIGINS |
Comma-separated URL list |
MAGIC_LINK_REDIRECT_URIS |
Comma-separated URL list |
OAUTH_PROVIDERS |
JSON array |
LOCKOUT_POLICY |
JSON object |
AUTHENTICATOR_POLICY |
JSON object |
FLOW_RATE_LIMITS |
JSON object |
RECOVERY_CODES |
JSON object |
ACCOUNT_RECOVERY |
JSON object |
RATE_LIMIT |
Number |
DELAY_AFTER |
Number |
MAX_CONCURRENT_SESSIONS |
Number; null, none, or unlimited (any case) means no cap; empty counts as unset |
PASSKEY_LOGIN_FALLBACK_ENABLED |
true means true; anything else is false |
PROMPT_PASSKEY_ENROLLMENT |
true means true; anything else is false |
PHISHING_RESISTANT_ONLY |
true means true; anything else is false |
ACCESS_TOKEN_TTL |
Duration string |
REFRESH_TOKEN_TTL |
Duration string |
SESSION_IDLE_TTL |
Duration string |
RPID |
String |
APP_NAME |
String |
FRONTEND_URL |
String |
JSON objects are stored as given. Fields left out of LOCKOUT_POLICY, AUTHENTICATOR_POLICY, or
FLOW_RATE_LIMITS take their schema defaults when the config is read, so a partial object such as
{"syncedPasskeys":"block"} is enough.
Duration strings in system config use:
30s15m1h7dThe current schema accepts s, m, h, and d for system config TTLs.
Login Methods
Section titled “Login Methods”Allowed values:
| Method | Meaning |
|---|---|
passkey |
WebAuthn/passkey login |
magic_link |
Email magic-link login |
email_otp |
Email one-time code |
phone_otp |
Phone/SMS one-time code |
oauth |
External OAuth provider login |
Example:
{ "login_methods": ["passkey", "magic_link", "email_otp", "phone_otp", "oauth"], "passkey_login_fallback_enabled": true}When passkey login is usable and passkey_login_fallback_enabled is false, the auth API returns
only passkey as the continuation method.
OAuth is configured as a login method, but it does not appear as a fallback from identifier-based
/login. Use /oauth/providers or listOAuthProviders() to render OAuth buttons.
default_roles are assigned to new users.
available_roles is the list operators can assign through admin flows.
Rules enforced on update:
- every
default_rolesvalue must exist inavailable_roles - roles currently assigned to users cannot be removed from
available_roles available_rolescannot remove a role that is still part of the existing default roles
Scoped admin roles are supported by auth route guards:
| Role | Grants |
|---|---|
admin |
broad admin access |
admin:read |
read access |
admin:write |
write access and read access |
Use the narrowest role that matches the route you are protecting.
OAuth Providers
Section titled “OAuth Providers”oauth_providers is an array of provider configs.
{ "oauth_providers": [ { "id": "google", "name": "Google", "enabled": true, "clientId": "google-client-id.apps.googleusercontent.com", "clientSecretEnv": "GOOGLE_CLIENT_SECRET", "authorizationUrl": "https://accounts.google.com/o/oauth2/v2/auth", "tokenUrl": "https://oauth2.googleapis.com/token", "userInfoUrl": "https://openidconnect.googleapis.com/v1/userinfo", "scopes": ["openid", "email", "profile"], "redirectUris": ["https://app.example.com/oauth/callback"], "subjectJsonPath": "sub", "emailJsonPath": "email", "emailVerifiedJsonPath": "email_verified", "nameJsonPath": "name", "allowSignup": true, "accountLinking": "email", "requireEmailVerified": true } ]}clientSecretEnv is an env var name. The actual provider secret must live in that env var, not in
system config.
redirectUri and redirectUris are allowlists. If present, requested OAuth callback URLs must
match exactly.
Lockout Policy
Section titled “Lockout Policy”Default policy:
{ "enabled": true, "maxFailures": 10, "windowSeconds": 900, "lockoutSeconds": 900}The current lockout policy counts recent failures for:
login_failedwebauthn_login_failedverify_otp_failedtotp_failedmagic_link_failed
When a user is locked, the auth API returns 423 with error: "account_locked" and
retryAfterSeconds.
Flow Rate Limits
Section titled “Flow Rate Limits”flow_rate_limits bounds how often one caller may drive a message-carrying, code-checking, or
provider flow. The general rate_limit still applies to every request.
Default:
{ "windowSeconds": 900, "otp": { "perIp": 10, "perIdentity": 5 }, "magicLink": { "perIp": 20, "perIdentity": 5 }, "oauth": { "perIp": 30, "perProvider": 10 }}| Field | Counts requests per window |
|---|---|
windowSeconds |
The window, in seconds, shared by every limiter |
otp.perIp |
OTP-group requests from one IP address |
otp.perIdentity |
OTP-group requests for one email address or phone |
magicLink.perIp |
GET /magic-link requests from one IP address |
magicLink.perIdentity |
GET /magic-link requests for one email address |
oauth.perIp |
OAuth start and callback requests from one IP |
oauth.perProvider |
OAuth start and callback requests from one IP, per provider |
The OTP group is one shared counter across /otp/*, POST /registration/register,
POST /registration/phone, and the TOTP enroll/verify, disable, verify-login, and
verify-mfa routes. A request with no email or phone to key on is counted by IP for the
per-identity limit.
Every value is a positive integer. A limit change takes effect on the next request; a
windowSeconds change starts fresh counters.
Mobile carriers put many subscribers behind one public address, so a deployment that serves
native apps usually raises the perIp values and leaves perIdentity alone. See
Mobile Passkeys.
WebAuthn Config
Section titled “WebAuthn Config”| Key | Use |
|---|---|
rpid |
Expected WebAuthn relying party ID |
origins |
Browser origins accepted for WebAuthn verification |
app_name |
Relying party display name during registration |
Local example:
{ "rpid": "localhost", "origins": ["http://localhost:5173", "http://localhost:5174"], "app_name": "Seamless Auth Example"}Production example:
{ "rpid": "example.com", "origins": ["https://app.example.com", "https://admin.example.com"], "app_name": "Example"}APP_ORIGINS is separate. It controls CORS for who may call the auth API. origins controls
WebAuthn verification.
Native apps add their own entries. iOS reports the relying party as https://<rpid>; Android
reports android:apk-key-hash:<base64url SHA-256 of the signing certificate>, one per
certificate. Keep the web origin first: origins[0] is the fallback for a request that gives no
origin of its own. See Mobile Passkeys.
Authenticator Policy
Section titled “Authenticator Policy”authenticator_policy decides which passkeys POST /webauthn/register/finish will store. It does
not affect credentials that are already registered.
Default:
{ "attachment": "any", "userVerification": "required", "attestation": "none", "requireKnownAuthenticator": false, "syncedPasskeys": "allow", "aaguidAllowList": [], "aaguidDenyList": []}| Field | Values | Effect |
|---|---|---|
attachment |
any, platform, cross-platform |
Authenticator kind offered at registration; a pinned value also bounds the attachment query on /webauthn/register/start |
userVerification |
required, preferred, discouraged |
Asked of the browser and enforced by the server for registration and login |
attestation |
none, direct |
Whether the authenticator is asked to identify itself with an attestation statement |
requireKnownAuthenticator |
boolean | Refuse an authenticator that cannot be matched against the FIDO Metadata Service |
syncedPasskeys |
allow, block |
Whether a credential that can sync off its authenticator may register |
aaguidAllowList |
AAGUID array | When non-empty, only these authenticator models may register |
aaguidDenyList |
AAGUID array | These authenticator models may not register |
Synced Passkeys
Section titled “Synced Passkeys”A passkey kept in iCloud Keychain, Google Password Manager, or another platform password manager
is synced, so its private key can exist outside the authenticator that created it. The server
judges this on WebAuthn backup eligibility (credentialDeviceType: "multiDevice"), not on whether
the credential has been backed up yet: a credential that can sync is the exposure.
allow registers synced passkeys. block refuses them with
403 {"error":"synced_passkey_not_allowed"}. Device-bound credentials, such as most hardware
security keys, register under either value.
AAGUID Allow And Deny Lists
Section titled “AAGUID Allow And Deny Lists”An AAGUID identifies an authenticator model, for example one make of security key. Entries are compared case-insensitively.
The server checks registration in this order, and the first rule that fails refuses it:
requireKnownAuthenticator: underattestation: "direct", a credential that self attests or presents no attestation is refusedaaguidDenyList: a listed AAGUID is refused, even when the allow list also names itaaguidAllowList: when non-empty, an AAGUID that is missing, all-zero, or unlisted is refusedsyncedPasskeys: underblock, a backup-eligible credential is refused
Rules 1 to 3 refuse with 403 {"error":"authenticator_not_allowed"}. Rule 4 refuses with
403 {"error":"synced_passkey_not_allowed"}. The audit event (webauthn_registration_failed)
records which rule refused, with the AAGUID and device type.
Both lists, and requireKnownAuthenticator, need attestation: "direct". An authenticator that
was not asked to identify itself can report an all-zero AAGUID, which no allow list admits and no
deny list entry matches. At startup the API logs an error when aaguidAllowList or
requireKnownAuthenticator is set while attestation is none.
Example for an organization that issues its own security keys:
{ "attachment": "cross-platform", "attestation": "direct", "requireKnownAuthenticator": true, "syncedPasskeys": "block", "aaguidAllowList": ["ee882879-721c-4913-9775-3dfcce97072a"]}See Auth API Routes for the registration error codes.
Runtime Cache
Section titled “Runtime Cache”seamless-auth-api caches system config in process and invalidates the cache after a successful
PATCH /system-config/admin.
If you edit the system_config table outside the API, expect existing processes to keep cached
values until they reload or the cache expires.
What Does Not Belong In System Config
Section titled “What Does Not Belong In System Config”Keep these in env vars or a secret manager:
API_SERVICE_TOKENCOOKIE_SIGNING_KEYREFRESH_TOKEN_LOOKUP_SECRETTOTP_SECRET_ENCRYPTION_KEYOAUTH_STATE_SECRET- OAuth provider client secrets such as
GOOGLE_CLIENT_SECRET SEAMLESS_JWKS_ACTIVE_KIDSEAMLESS_JWKS_KEY_<kid>_PRIVATESEAMLESS_JWKS_PUBLIC_KEYS
System config may reference secret env var names, such as clientSecretEnv, but should not contain
raw secret values.
Safe Update Pattern
Section titled “Safe Update Pattern”- Read current config from
/auth/system-config/admin. - Patch only the keys you intend to change.
- Confirm the response includes the expected
updatedKeys. - Test login, WebAuthn, OAuth, and admin flows affected by the change.
- Keep env vars aligned for any secrets referenced by system config.
Example patch:
{ "login_methods": ["passkey", "magic_link", "email_otp"], "passkey_login_fallback_enabled": true}