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/organization
PUT    /orgs/{orgId}/api/v1/admin/organization

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

Authentication​

All settings endpoints require a valid admin API key or a Bearer token issued to a user with settings.manage permission.

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"
All Settings Response
{
  "data": {
    "data": {
      "general": { "name": "Acme Corp", "supportEmail": "support@acme.com" },
      "authentication": { "passwordMinLength": 10, "mfaRequired": false },
      "security": { "sessionTimeout": 86400, "maxLoginAttempts": 5 },
      "email": { "fromName": "Acme Corp Auth", "fromEmail": "noreply@acme.com" }
    }
  }
}

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",
    "supportEmail": "auth-support@acme.com",
    "logoUrl": "https://cdn.acme.com/logo.png"
  }'

Authentication Settings​

Controls password policies, MFA requirements, and login behaviour.

Get Authentication Settings​

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

Update Authentication Settings​

Update Authentication 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 '{
    "passwordMinLength": 12,
    "passwordRequireUppercase": true,
    "passwordRequireNumbers": true,
    "passwordRequireSymbols": true,
    "mfaRequired": true,
    "mfaMethods": ["totp", "webauthn"],
    "allowPasswordLogin": true,
    "allowSocialLogin": true,
    "sessionDuration": 86400
  }'

Authentication Settings Fields​

FieldTypeDescription
passwordMinLengthintegerMinimum password length (default: 8)
passwordRequireUppercasebooleanRequire at least one uppercase letter
passwordRequireNumbersbooleanRequire at least one digit
passwordRequireSymbolsbooleanRequire at least one symbol
mfaRequiredbooleanForce all users to enroll in MFA
mfaMethodsarrayAllowed MFA methods: totp, webauthn, sms, email
allowPasswordLoginbooleanAllow username/password login
allowSocialLoginbooleanAllow social provider login
sessionDurationintegerSession lifetime in seconds

Security Settings​

Controls brute-force protection, IP allowlisting, and token configuration.

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 '{
    "maxLoginAttempts": 5,
    "lockoutDuration": 900,
    "sessionTimeout": 3600,
    "accessTokenTtl": 3600,
    "refreshTokenTtl": 2592000
  }'

Security Settings Fields​

FieldTypeDescription
maxLoginAttemptsintegerFailed logins before lockout
lockoutDurationintegerLockout duration in seconds
sessionTimeoutintegerIdle session timeout in seconds
accessTokenTtlintegerAccess token TTL in seconds
refreshTokenTtlintegerRefresh token TTL in seconds
requirePkcebooleanRequire PKCE for all OAuth flows

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, slug, metadata).

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",
    "metadata": { "plan": "enterprise", "region": "us-east-1" }
  }'