Skip to content

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.


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:

  1. if a row exists and updatedBy is set, the API uses the row and ignores the env var
  2. if a row exists, updatedBy is NULL, 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
  3. if a row exists and the mapped env var is unset or empty, the API uses the row
  4. if no row exists and the mapped env var is set, the API parses the env var and creates the row
  5. if no row exists and the key has a built-in default, the API creates the row with that default
  6. 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.


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/:id

Successful 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.


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 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:

30s
15m
1h
7d

The current schema accepts s, m, h, and d for system config TTLs.


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_roles value must exist in available_roles
  • roles currently assigned to users cannot be removed from available_roles
  • available_roles cannot 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 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.


Default policy:

{
"enabled": true,
"maxFailures": 10,
"windowSeconds": 900,
"lockoutSeconds": 900
}

The current lockout policy counts recent failures for:

  • login_failed
  • webauthn_login_failed
  • verify_otp_failed
  • totp_failed
  • magic_link_failed

When a user is locked, the auth API returns 423 with error: "account_locked" and retryAfterSeconds.


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.


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 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

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.

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:

  1. requireKnownAuthenticator: under attestation: "direct", a credential that self attests or presents no attestation is refused
  2. aaguidDenyList: a listed AAGUID is refused, even when the allow list also names it
  3. aaguidAllowList: when non-empty, an AAGUID that is missing, all-zero, or unlisted is refused
  4. syncedPasskeys: under block, 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.


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.


Keep these in env vars or a secret manager:

  • API_SERVICE_TOKEN
  • COOKIE_SIGNING_KEY
  • REFRESH_TOKEN_LOOKUP_SECRET
  • TOTP_SECRET_ENCRYPTION_KEY
  • OAUTH_STATE_SECRET
  • OAuth provider client secrets such as GOOGLE_CLIENT_SECRET
  • SEAMLESS_JWKS_ACTIVE_KID
  • SEAMLESS_JWKS_KEY_<kid>_PRIVATE
  • SEAMLESS_JWKS_PUBLIC_KEYS

System config may reference secret env var names, such as clientSecretEnv, but should not contain raw secret values.


  1. Read current config from /auth/system-config/admin.
  2. Patch only the keys you intend to change.
  3. Confirm the response includes the expected updatedKeys.
  4. Test login, WebAuthn, OAuth, and admin flows affected by the change.
  5. 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
}