Tenant Settings

Overview

Tenant settings are stored as a JSON object in the database and cached in Redis for fast access. When you update settings via the API, changes take effect immediately — the cache is invalidated and all subsequent authentication and authorization operations use the new values.

The settings object is divided into logical sections. You can update one section at a time or multiple sections in a single request. Updates use deep merge semantics — only the fields you include are changed; everything else remains untouched.

Settings Sections

The settings object contains 7 top-level sections. Each section controls a specific aspect of tenant behavior.

password_policy

Controls password strength requirements and rotation rules. Applied at registration, password change, and password reset.

mfa

Controls multi-factor authentication availability and enforcement for the tenant.

session

Controls token lifetimes, idle timeouts, and concurrent session limits.

risk_engine

Controls the behavioral risk engine that scores login attempts and triggers challenges or blocks.

ip_access

IP allowlist/blocklist configuration. When enabled, restricts login to specific IP addresses or CIDR ranges.

branding

Customize the appearance of hosted login pages and email templates.

notifications

Control which email notifications are sent to users automatically.

Reading Settings

Retrieve the full settings object for your tenant. The response includes all sections with their current values (including defaults for any fields you haven't explicitly set).

GET/api/v1/settings🔒 Auth

Retrieve the complete tenant settings object.

RequestResponse

cURLJavaScriptPythonGoPHP

curl -X GET https://id.vyntech.com.au/api/v1/settings \ -H "Authorization: Bearer eyJhbGciOiJFZERTQSIs..."

Updating Settings

Update one or more settings sections with a single PATCH request. The API uses deep merge — only the fields you include in the request body are modified. Omitted fields retain their current values.

PATCH/api/v1/settings🔒 Auth

Update tenant settings (deep merge). Only include fields you want to change.

RequestResponse

cURLJavaScriptPythonGoPHP

curl -X PATCH https://id.vyntech.com.au/api/v1/settings \ -H "Authorization: Bearer eyJhbGciOiJFZERTQSIs..." \ -H "Content-Type: application/json" \ -d '{ "password_policy": { "min_length": 12, "require_symbols": true, "max_age_days": 90, "history_count": 5 }, "session": { "access_token_ttl_seconds": 600, "idle_timeout_seconds": 1800, "max_concurrent_sessions": 3 } }'

Request Body

{
  "password_policy": {
    "min_length": 12,
    "require_symbols": true,
    "max_age_days": 90,
    "history_count": 5
  },
  "session": {
    "access_token_ttl_seconds": 600,
    "idle_timeout_seconds": 1800,
    "max_concurrent_sessions": 3
  }
}

Common Configurations

Here are three battle-tested configuration patterns for different security postures. Copy and adapt these to your needs.

Enterprise Security

Maximum security posture: strict password requirements, mandatory MFA, short sessions, aggressive risk engine. Ideal for financial services, healthcare, and government.

PATCH/api/v1/settings🔒 Auth

Enterprise security configuration — maximum protection.

RequestResponse

cURLJavaScriptPythonGoPHP

curl -X PATCH https://id.vyntech.com.au/api/v1/settings \ -H "Authorization: Bearer eyJhbGciOiJFZERTQSIs..." \ -H "Content-Type: application/json" \ -d '{ "password_policy": { "min_length": 14, "require_uppercase": true, "require_lowercase": true, "require_numbers": true, "require_symbols": true, "max_age_days": 60, "history_count": 12 }, "mfa": { "enabled": true, "enforced": true }, "session": { "access_token_ttl_seconds": 300, "refresh_token_ttl_seconds": 28800, "idle_timeout_seconds": 900, "max_concurrent_sessions": 2, "absolute_timeout_seconds": 28800 }, "risk_engine": { "enabled": true, "challenge_threshold": 50, "block_threshold": 75, "trust_device_days": 7 } }'

Developer-Friendly

Balanced security with minimal friction: reasonable password rules, optional MFA, longer sessions for better developer experience. Good for internal tools and dev environments.

PATCH/api/v1/settings🔒 Auth

Developer-friendly configuration — balanced security with low friction.

RequestResponse

cURLJavaScriptPythonGoPHP

curl -X PATCH https://id.vyntech.com.au/api/v1/settings \ -H "Authorization: Bearer eyJhbGciOiJFZERTQSIs..." \ -H "Content-Type: application/json" \ -d '{ "password_policy": { "min_length": 8, "require_uppercase": true, "require_lowercase": true, "require_numbers": true, "require_symbols": false, "max_age_days": 0, "history_count": 0 }, "mfa": { "enabled": true, "enforced": false }, "session": { "access_token_ttl_seconds": 3600, "refresh_token_ttl_seconds": 2592000, "idle_timeout_seconds": 0, "max_concurrent_sessions": 10 }, "risk_engine": { "enabled": true, "challenge_threshold": 80, "block_threshold": 95, "trust_device_days": 90 } }'

Compliance Mode

Meets common compliance requirements (SOC 2, HIPAA, PCI-DSS): password rotation, session limits, IP restrictions, and mandatory notifications. Suitable for regulated industries.

PATCH/api/v1/settings🔒 Auth

Compliance mode configuration — meets SOC 2, HIPAA, PCI-DSS requirements.

RequestResponse

cURLJavaScriptPythonGoPHP

curl -X PATCH https://id.vyntech.com.au/api/v1/settings \ -H "Authorization: Bearer eyJhbGciOiJFZERTQSIs..." \ -H "Content-Type: application/json" \ -d '{ "password_policy": { "min_length": 12, "require_uppercase": true, "require_lowercase": true, "require_numbers": true, "require_symbols": true, "max_age_days": 90, "history_count": 10 }, "mfa": { "enabled": true, "enforced": true }, "session": { "access_token_ttl_seconds": 900, "refresh_token_ttl_seconds": 86400, "idle_timeout_seconds": 1800, "max_concurrent_sessions": 3, "absolute_timeout_seconds": 43200 }, "ip_access": { "enabled": true, "mode": "allowlist", "addresses": ["10.0.0.0/8", "172.16.0.0/12", "192.168.0.0/16"] }, "notifications": { "welcome_email": true, "login_alert": true, "password_change_alert": true } }'

Best Practices

What's Next