Skip to main content

Settings

GET    /orgs/{orgId}/api/v1/admin/settings
GET    /orgs/{orgId}/api/v1/admin/settings/general
PUT    /orgs/{orgId}/api/v1/admin/settings/general
PATCH  /orgs/{orgId}/api/v1/admin/settings/general
GET    /orgs/{orgId}/api/v1/admin/settings/authentication
PUT    /orgs/{orgId}/api/v1/admin/settings/authentication
PATCH  /orgs/{orgId}/api/v1/admin/settings/authentication
GET    /orgs/{orgId}/api/v1/admin/settings/security
PUT    /orgs/{orgId}/api/v1/admin/settings/security
PATCH  /orgs/{orgId}/api/v1/admin/settings/security
GET    /orgs/{orgId}/api/v1/admin/settings/email
PUT    /orgs/{orgId}/api/v1/admin/settings/email
PATCH  /orgs/{orgId}/api/v1/admin/settings/email
GET    /orgs/{orgId}/api/v1/admin/settings/auth
PUT    /orgs/{orgId}/api/v1/admin/settings/auth
PATCH  /orgs/{orgId}/api/v1/admin/settings/auth
GET    /orgs/{orgId}/api/v1/admin/settings/branding
PUT    /orgs/{orgId}/api/v1/admin/settings/branding
PATCH  /orgs/{orgId}/api/v1/admin/settings/branding
GET    /orgs/{orgId}/api/v1/admin/settings/scim
PUT    /orgs/{orgId}/api/v1/admin/settings/scim
PATCH  /orgs/{orgId}/api/v1/admin/settings/scim
GET    /orgs/{orgId}/api/v1/admin/organization
PUT    /orgs/{orgId}/api/v1/admin/organization
note

/settings/auth is a shorter alias of /settings/authentication. The branding category exposes the hosted-login appearance (logo, colours, layout — see the branding block in the all-settings response), and scim exposes the SCIM provisioning configuration. All three follow the same GET / PUT / PATCH shape as the categories below.

Branding values are validated exactly as in the portal: enumerated fields (layout, theme, background_type, input_style, …) fall back to their default when the value is unknown, colours must be hex (or a basic colour name, stored as hex), image and link fields must be http(s) URLs, and custom_css / custom_html are filtered as described in Login Page & Branding. A refused value comes back as null in the response.

Organization settings control authentication behaviour, security policies, email configuration, and general organization information.

Secrets are redacted​

Settings responses never return credential material. Every value stored under a secret-looking key (client_secret, basic_password, oauth2_client_secret, bearer_token_hash, initial_access_tokens, api_key, credentials, anything containing private_key, …) is replaced by a marker:

{ "client_secret": { "configured": true, "redacted": true } }

Settings about a secret stay readable (bearer_token_preview, token_created_at, public_key, booleans and lifetimes). Sending the marker back in a PUT or PATCH, for example when you round-trip a fetched payload, leaves the stored value unchanged; send a new string to replace a secret.

SCIM settings​

GET /admin/settings/scim returns inbound (LumoAuth as SCIM server) and outbound (LumoAuth pushing to another SCIM server) blocks.

  • Inbound bearer_token is write-only. Send it to set the provisioning token; LumoAuth stores only its SHA-256 hash and returns bearer_token_preview and the creation time. The hash, preview and creation time cannot be written directly. Other writable inbound keys: enabled, allow_user_creation, allow_user_updates, allow_user_deletion, allow_group_operations, auto_activate_users, protected_attributes, attribute_mapping and deprovisioning_action (soft_delete, deactivate, hard_delete).
  • Outbound authentication (auth_type) is bearer, basic or oauth2. OAuth 2.0 client credentials use oauth2_client_id, oauth2_client_secret, oauth2_token_url and optional oauth2_scope. The secret fields (bearer_token, basic_password, oauth2_client_secret) are encrypted at rest, redacted on read and may be secret:// references to a secrets manager. Changing endpoint_url or oauth2_token_url requires re-entering the secret.

Authentication​

All settings endpoints require an API key or a Bearer token carrying admin:settings:read (for GET) or admin:settings:write (for PUT/PATCH). See Authentication.

Each endpoint needs the credential's scope and a permission. A session or Bearer caller must hold the permission; for an API key its creator must still hold it. A missing permission returns 403 forbidden with details.required_permissions. See Required permissions.

MethodEndpointPermissionAPI-key / token scope
GET/admin/settingssettings.viewadmin:settings:read
GET/admin/settings/generalsettings.viewadmin:settings:read
PATCH PUT/admin/settings/generalsettings.editadmin:settings:write
GET/admin/settings/authenticationsettings.viewadmin:settings:read
PATCH PUT/admin/settings/authenticationsettings.manageadmin:settings:write
GET/admin/settings/securitysettings.viewadmin:settings:read
PATCH PUT/admin/settings/securitysettings.manageadmin:settings:write
GET/admin/settings/emailsettings.viewadmin:settings:read
PATCH PUT/admin/settings/emailsettings.editadmin:settings:write
GET/admin/tenantsettings.viewadmin:settings:read
GET/admin/organizationsettings.viewadmin:settings:read
PUT PATCH/admin/tenantsettings.manageadmin:settings:write
PUT PATCH/admin/organizationsettings.manageadmin:settings:write
GET/admin/settings/authsettings.viewadmin:settings:read
PUT PATCH/admin/settings/authsettings.manageadmin:settings:write
GET/admin/settings/brandingbranding.viewadmin:settings:read
PUT PATCH/admin/settings/brandingbranding.editadmin:settings:write
GET/admin/settings/scimscim.viewadmin:settings:read
PUT PATCH/admin/settings/scimscim.editadmin:settings:write
GET/admin/analytics/dashboardanalytics.viewadmin:analytics:read
GET/admin/analytics/loginsanalytics.viewadmin:analytics:read
GET/admin/analytics/usersanalytics.viewadmin:analytics:read
GET/admin/email-templatessettings.viewadmin:settings:read
GET/admin/email-templates/{type}settings.viewadmin:settings:read
PUT/admin/email-templates/{type}settings.editadmin:settings:write
DELETE/admin/email-templates/{type}settings.editadmin:settings:write
POST/admin/email-templates/{type}/previewsettings.editadmin:settings:write
GET/admin/email-templates/{type}/variablessettings.viewadmin:settings:read
POST/admin/sandbox/spawnsettings.manageadmin:settings:write
GET/admin/sandboxsettings.viewadmin:settings:read
POST/admin/sandbox/{sandboxSlug}/destroysettings.manageadmin:settings:write

Get All Settings​

Returns all setting categories in a single response.

Get All Settings
curl "https://app.lumoauth.dev/orgs/acme-corp/api/v1/admin/settings" \
  -H "Authorization: ApiKey lmk_abc123"

GET responses return each category's stored settings using snake_case keys (the raw stored shape):

All Settings Response
{
  "data": {
    "general": { "name": "Acme Corp" },
    "authentication": {
      "password_min_length": 8,
      "mfa_required": false,
      "mfa_methods": [],
      "social_login_enabled": false,
      "passkey_enabled": false,
      "session_timeout": 1209600
    },
    "branding": { "enabled": false, "primary_color": "#667eea" },
    "security": [],
    "email": []
  }
}
note

Keys are stored as sent. Each category's PUT/PATCH body is merged into the stored settings under the same key names, and GET returns exactly what is stored. Use the snake_case names shown in the GET responses when you update; a differently cased key is stored as a new, unread key rather than mapped.

General Settings​

Get General Settings​

Get General Settings
curl "https://app.lumoauth.dev/orgs/acme-corp/api/v1/admin/settings/general" \
  -H "Authorization: ApiKey lmk_abc123"

Update General Settings​

Update General Settings
curl -X PATCH https://app.lumoauth.dev/orgs/acme-corp/api/v1/admin/settings/general \
  -H "Authorization: ApiKey lmk_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corporation",
    "display_name": "Acme",
    "timezone": "Europe/Berlin",
    "locale": "en"
  }'

General Settings Fields​

FieldTypeDescription
namestringOrganization display name (alias: tenantName)
display_namestringName shown on hosted pages (alias: displayName)
timezonestringIANA time zone, for example Europe/Berlin
localestringDefault locale, for example en

Other keys in a general-settings body are ignored.

Sign-in settings​

Controls password policies, MFA requirements, and login behaviour.

Get Sign-in settings​

Get Sign-in settings
curl "https://app.lumoauth.dev/orgs/acme-corp/api/v1/admin/settings/authentication" \
  -H "Authorization: ApiKey lmk_abc123"

Update Sign-in settings​

Update Sign-in settings
curl -X PATCH https://app.lumoauth.dev/orgs/acme-corp/api/v1/admin/settings/authentication \
  -H "Authorization: ApiKey lmk_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "password_min_length": 12,
    "password_require_special": true,
    "social_login_enabled": true,
    "session_timeout": 86400
  }'

Sign-in settings Fields​

The body uses the same snake_case keys the GET response returns (see the full object on the Organization settings page). The most common:

FieldTypeDescription
password_min_lengthintegerMinimum password length (default: 8)
password_require_specialbooleanRequire at least one symbol
password_policyobjecttemplate, min_length, require_special, require_numbers, require_uppercase, require_lowercase
password_rotation_policyobjectenabled, max_age_days, notify_before_days, history_count
mfa_policyobjectThe organization MFA policy (requirement, allowed factors, tiers, grace period, trusted devices, SMS rules). Read and change it through GET/PUT /admin/policies/mfa; see the policy reference
mfa_requiredbooleanLegacy. Mirrors mfa_policy.requirement == "required". Writing it changes the policy: true → required, false → risk_based
mfa_sms_enabledbooleanLegacy. Mirrors whether sms_otp is in mfa_policy.allowed_factors; writing it adds or removes sms_otp
mfa_methodsarrayLegacy. Only read (for email) when no mfa_policy exists
no_mfa_actionstringAdaptive auth: what to do on a risky sign-in by a user with no MFA factor (allow, prompt, email, block)
passkey_enabledbooleanAllow passkey (WebAuthn) sign-in
social_login_enabledbooleanAllow social provider login
session_timeoutintegerSession lifetime in seconds
dynamic_client_registration_enabledbooleanAllow dynamic client registration: applications registering themselves through the API (an initial access token is still required unless require_initial_access_token is false)

social_configs secrets (client_secret, private_key) are merged with the stored values, so you can update a provider without resending its secret.

MFA keys are routed through the MFA policy

mfa_policy (a partial object), mfa_required and mfa_sms_enabled sent to this endpoint are not stored as sent: they are applied as an MFA policy change, validated and clamped exactly like PUT /admin/policies/mfa, and the legacy keys are kept in sync. mfa_required: true sets the requirement to required, false sets it to risk_based; mfa_sms_enabled adds or removes sms_otp in allowed_factors. Prefer the policy endpoint for new integrations.

Security Settings​

The security block holds OAuth hardening switches that apply to the whole organization. It is stored as sent and returned verbatim by GET; the platform reads the keys listed under Security Settings Fields.

Brute-force protection (5 failed logins per IP and per e-mail in 15 minutes, then a 15-minute account lock) is platform-wide and is not configurable here; see Rate limits.

Get Security Settings​

Get Security Settings
curl "https://app.lumoauth.dev/orgs/acme-corp/api/v1/admin/settings/security" \
  -H "Authorization: ApiKey lmk_abc123"

Update Security Settings​

Update Security Settings
curl -X PATCH https://app.lumoauth.dev/orgs/acme-corp/api/v1/admin/settings/security \
  -H "Authorization: ApiKey lmk_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "dpop_require_nonce": true
  }'

Security Settings Fields​

FieldTypeDefaultDescription
dpop_require_noncebooleanfalseRequire a server-issued nonce in every DPoP proof (DPoP ties a token to the client's key so a stolen copy cannot be replayed). When true, the token endpoint answers a proof without a fresh nonce with 400 use_dpop_nonce and DPoP-protected resources with 401 use_dpop_nonce, each carrying a DPoP-Nonce header the client must echo in its next proof. Turn it on only for clients that implement the retry; see DPoP.

PATCH /settings/security merges the body into the stored security block key by key, so you can flip one switch without resending the others. The same block can be written through PATCH /admin/organization (settings.security), but that path replaces the whole security object; prefer this endpoint for single-key changes.

The organization-level allow_root_admin_login switch is not part of security and is not writable through the API; it is changed only by LumoAuth operators at your request. See allow_root_admin_login.

Email Settings​

Configures outbound email — sender address and optional SMTP overrides.

Get Email Settings​

Get Email Settings
curl "https://app.lumoauth.dev/orgs/acme-corp/api/v1/admin/settings/email" \
  -H "Authorization: ApiKey lmk_abc123"

Update Email Settings​

Update Email Settings
curl -X PATCH https://app.lumoauth.dev/orgs/acme-corp/api/v1/admin/settings/email \
  -H "Authorization: ApiKey lmk_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "fromName": "Acme Corp Auth",
    "fromEmail": "noreply@acme.com",
    "replyToEmail": "support@acme.com"
  }'

Organization Profile​

Get or update the top-level organization profile: name and the allow-listed settings keys. There is no free-form metadata; any settings key outside the allow-list is rejected with 400 invalid_request and details.rejected_keys. The full contract is on the Organization settings page.

Get Organization​

Get Organization Profile
curl "https://app.lumoauth.dev/orgs/acme-corp/api/v1/admin/organization" \
  -H "Authorization: ApiKey lmk_abc123"

Update Organization​

Update Organization Profile
curl -X PUT https://app.lumoauth.dev/orgs/acme-corp/api/v1/admin/organization \
  -H "Authorization: ApiKey lmk_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corporation",
    "settings": { "timezone": "America/New_York", "locale": "en" }
  }'

Standards used on this page​

Plain nameStandard
SCIM 2.0 (user and group provisioning)RFC 7642, RFC 7643 and RFC 7644
Dynamic client registrationRFC 7591 and RFC 7592
Sender-constrained tokens (DPoP)RFC 9449

See the standards reference for what each one covers and how LumoAuth uses it.