REST API Reference v2.1 -- Organization Settings
GET /org/settings
Returns the current organization settings. Requires org:read scope. The response includes all configurable settings grouped by category: authentication, security, notifications, and integrations.
Response: {"authentication": {"sso_enabled": true, "sso_provider": "okta", "sso_entity_id": "https://example.okta.com/...", "mfa_required": true, "session_timeout_minutes": 480}, "security": {"ip_allowlist": ["203.0.113.0/24", "198.51.100.0/24"], "ip_allowlist_enabled": true, "minimum_password_length": 12, "api_key_max_age_days": 90}, "notifications": {"email_enabled": true, "slack_webhook": "https://hooks.slack.com/...", "alert_channels": {"critical": ["email", "slack", "pagerduty"], "high": ["email", "slack"]}}}.
PUT /org/settings/authentication
Configures authentication settings for the organization. Requires org:admin scope. Request body: {"sso_enabled": true, "sso_provider": "saml", "sso_metadata_url": "https://example.okta.com/app/metadata", "mfa_required": true, "mfa_methods": ["totp", "webauthn"], "session_timeout_minutes": 480, "session_max_lifetime_hours": 24}. When SSO is enabled, all users must authenticate through the configured identity provider. Local password authentication is disabled.
MFA configuration requires at least one method from: totp (authenticator app), webauthn (hardware security keys like YubiKey), sms (not recommended for high-security environments). WebAuthn is recommended as the primary MFA method because it is phishing-resistant and provides the strongest assurance of user identity.
PUT /org/settings/security
Configures organization-wide security policies. Request body: {"ip_allowlist_enabled": true, "ip_allowlist": ["203.0.113.0/24"], "api_key_max_age_days": 90, "minimum_password_length": 14, "password_complexity": {"require_uppercase": true, "require_number": true, "require_symbol": true}, "failed_login_lockout": {"max_attempts": 5, "lockout_duration_minutes": 30}}.
IP allowlist enforcement applies to both web UI access and API requests. When enabled, requests from IP addresses outside the allowlist receive a 403 Forbidden response. Service accounts can be exempted from IP restrictions by adding the bypass_ip_allowlist scope to their tokens, but this should be used sparingly and audited regularly.
Peer-reviewed and accepted for publication. Supplementary data available via linked endpoints.