API Reference: Org Settings

API Reference: Org Settings

Base path: /api/v1/admin/org

Org settings control organization-wide configuration: display name, allowed email domains, session behavior, MFA policy, data retention, and feature flags. All endpoints require an admin-scoped token.

---

Get Organization Settings

GET /api/v1/admin/org/settings
Authorization: Bearer <admin-token>

Response 200 OK:

{
  "org_id": "org_01HXYZ",
  "display_name": "Acme Corp",
  "slug": "acme-corp",
  "allowed_domains": ["acme.com", "acme.io"],
  "contact_email": "[email protected]",
  "timezone": "America/New_York",
  "session_timeout_minutes": 480,
  "idle_timeout_minutes": 60,
  "ip_allowlist": ["203.0.113.0/24"],
  "feature_flags": {
    "dlp_enabled": true,
    "credential_intelligence": true,
    "human_in_loop": false,
    "budget_enforcement": true,
    "outpost_enabled": true
  },
  "created_at": "2025-06-01T00:00:00Z",
  "updated_at": "2026-03-01T09:00:00Z"
}

---

Update Organization Settings

PUT /api/v1/admin/org/settings
Authorization: Bearer <admin-token>
Content-Type: application/json

All fields are optional — only provided fields are updated.

Request body:

{
  "display_name": "Acme Corporation",
  "contact_email": "[email protected]",
  "timezone": "UTC",
  "session_timeout_minutes": 240,
  "idle_timeout_minutes": 30,
  "ip_allowlist": ["203.0.113.0/24", "198.51.100.0/24"],
  "feature_flags": {
    "human_in_loop": true
  }
}

Response 200 OK: Updated settings object.

Validation errors 422 Unprocessable Entity:

{
  "error": "validation_error",
  "details": [
    {"field": "session_timeout_minutes", "message": "Must be between 15 and 1440"},
    {"field": "ip_allowlist", "message": "Invalid CIDR: 999.0.0.0/8"}
  ]
}

---

Allowed Domains

List Allowed Domains

GET /api/v1/admin/org/allowed-domains
Authorization: Bearer <admin-token>

{
  "domains": ["acme.com", "acme.io"],
  "jit_provisioning": true,
  "default_group_id": "grp_01HXYZ"
}

Add Allowed Domain

POST /api/v1/admin/org/allowed-domains
Authorization: Bearer <admin-token>
Content-Type: application/json

{
  "domain": "acme-labs.com",
  "jit_provisioning": true,
  "default_group_id": "grp_01HXYZ"
}

Response 201 Created: Domain entry object.

Duplicate domain returns 409 Conflict.

Remove Allowed Domain

DELETE /api/v1/admin/org/allowed-domains/{domain}
Authorization: Bearer <admin-token>

Response 204 No Content.

---

Session Policy

Get Session Policy

GET /api/v1/admin/org/session-policy
Authorization: Bearer <admin-token>

{
  "session_timeout_minutes": 480,
  "idle_timeout_minutes": 60,
  "concurrent_sessions": "unlimited",
  "enforce_single_session": false,
  "refresh_token_enabled": true,
  "refresh_token_ttl_days": 30
}

Update Session Policy

PUT /api/v1/admin/org/session-policy
Authorization: Bearer <admin-token>
Content-Type: application/json

{
  "session_timeout_minutes": 240,
  "idle_timeout_minutes": 30,
  "enforce_single_session": true,
  "refresh_token_ttl_days": 7
}

concurrent_sessions values: "unlimited" | "1" | "2" | "5"

---

MFA Policy

See the MFA Enforcement guide for full details.

Get MFA Policy

GET /api/v1/admin/org/mfa-policy
Authorization: Bearer <admin-token>

{
  "enforcement_level": "optional",
  "sensitive_endpoints_require_mfa": true,
  "mfa_methods": ["totp", "webauthn"],
  "grace_period_hours": 0,
  "mfa_assertion_ttl_seconds": 3600,
  "enrollment_deadline": null
}

Update MFA Policy

PUT /api/v1/admin/org/mfa-policy
Authorization: Bearer <admin-token>
Content-Type: application/json

{
  "enforcement_level": "required",
  "mfa_methods": ["totp", "webauthn"],
  "grace_period_hours": 48,
  "enrollment_deadline": "2026-04-01T00:00:00Z"
}

enforcement_level values: "off" | "optional" | "required"

---

Data Retention Policy

GET /api/v1/admin/retention/policy
Authorization: Bearer <admin-token>

{
  "hot_retention_days": 30,
  "warm_retention_days": 90,
  "cold_retention_years": 7,
  "archiver_schedule": "0 2 * * *",
  "last_archival_run": "2026-03-12T02:00:00Z",
  "last_archival_status": "success",
  "rows_archived_last_run": 48293
}

PUT /api/v1/admin/retention/policy
Authorization: Bearer <admin-token>
Content-Type: application/json

{
  "hot_retention_days": 45,
  "warm_retention_days": 90
}

---

Feature Flags

Feature flags can be toggled individually without a full settings update.

Get Feature Flags

GET /api/v1/admin/org/feature-flags
Authorization: Bearer <admin-token>

{
  "dlp_enabled": true,
  "credential_intelligence": true,
  "human_in_loop": false,
  "budget_enforcement": true,
  "outpost_enabled": true,
  "api_key_scoping": true,
  "audit_log_streaming": false,
  "cost_routing": true
}

Toggle Feature Flag

PATCH /api/v1/admin/org/feature-flags/{flag_name}
Authorization: Bearer <admin-token>
Content-Type: application/json

{
  "enabled": true
}

Response 200 OK:

{
  "flag": "human_in_loop",
  "enabled": true,
  "updated_at": "2026-03-12T10:00:00Z"
}

Unknown flag name returns 404 Not Found.

---

IP Allowlist

Get IP Allowlist

GET /api/v1/admin/org/ip-allowlist
Authorization: Bearer <admin-token>

{
  "enabled": true,
  "cidrs": ["203.0.113.0/24", "198.51.100.42/32"],
  "bypass_for_mfa": false
}

Update IP Allowlist

PUT /api/v1/admin/org/ip-allowlist
Authorization: Bearer <admin-token>
Content-Type: application/json

{
  "enabled": true,
  "cidrs": ["203.0.113.0/24"],
  "bypass_for_mfa": false
}

Setting "enabled": false disables allowlist enforcement without deleting the CIDR list.

Warning: Setting an IP allowlist that excludes your current IP will lock you out. The API validates that the request IP is within the new allowlist before applying it.

---

Error Reference

Status	Code	Description
400	invalid_request	Malformed JSON or missing required field
401	unauthorized	Missing or invalid token
403	forbidden	Token lacks admin scope
403	mfa_required	Sensitive operation requires MFA step-up
422	validation_error	Field value out of range or invalid format

---

Related

• MFA Enforcement Guide
• Data Retention & Archival Guide
• SCIM Provisioning API