Skip to content

Update organization

PATCH /organization/{id}

Requires the `org:manage` permission and an active Gold or Black subscription — except a body that sets only `allow_staff_impersonation` and/or `mfa_required`, which is accepted whatever the plan. **`settings` is REPLACED wholesale, not merged**: whatever object you send becomes the entire settings object, so any key you omit is deleted. Read the current organization first and send the merged result. `name` and `allow_staff_impersonation` are normal field updates, and omitting a field leaves it untouched. `mfa_required` is a sign-in policy and has its own rules: it needs an interactive browser session (an API token answers 403, and the AI surfaces do not accept the field at all), it is refused to a staff impersonation session, turning it OFF needs step-up reauthentication (`428 step_up_required`, action `organization.mfa-requirement.disable`), and turning it ON answers `409 mfa_setup_required` when the caller's own session would fail the check — see `can_require_mfa` on the response. A change is recorded in the `organization.updated` audit entry with the old and new value in its `mfa_required` metadata. `slug`, `plan` and `region` cannot be changed here.

Path Parameters

idstring
required·

Organization id (org_…).

Request Body

allow_staff_impersonationboolean

false refuses Elaichi staff impersonation for this organization — every request, reads included. Recorded in the organization.updated audit entry: the field is named in fields and the value it was set to is in the entry's allow_staff_impersonation metadata.

mfa_requiredboolean

true requires every member to hold a second factor to act in this organization; false lifts it. See the operation description for who may change it and what a change needs.

namestring
settingsRecord<string, any>

Replaces the stored settings object entirely. Omitted keys are lost.

Response Body

allow_staff_impersonationboolean

Whether Elaichi staff may impersonate this organization's members for support. true by default. When false, every request an impersonated session makes against this organization is refused with 403 staff_impersonation_blocked, reads included, and the organization is left out of that session's GET /user/me and GET /organization. Changed with PATCH /organization/{id} (org:manage).

authorize_apps_blocked_reasonstring,null

Why can_authorize_apps is false, in the gate's own order: blocked, then pending_deletion (even when the subscription is also gone, since a soft delete cancels it), then no_plan. null when connecting is open.

Possible values:
blockedpending_deletionno_plannull
can_authorize_appsboolean

Whether the CALLER may connect an app (MCP OAuth consent) to this organization right now: false while it is suspended, scheduled for deletion, or has no active plan. Server-computed by the same gate POST /oauth/authorize-request/{id}/approve calls; present only on member-scoped responses. authorize_apps_blocked_reason says which.

can_deleteboolean

Whether the CALLER may delete this organization — the org:delete permission, which only the Org Owner role holds, and never for the platform root organization. Server-computed: branch on this rather than inspecting roles. Always false where the response has no member context to compute it from — the org switcher list GET /organization (one member-context lookup per row would be a per-row round trip), the staff console, and the invite-accept response. It never overstates: trust it when true, and read GET /user/me or GET /organization/{id} (both of which compute it) when you need it for a list row.

can_manageboolean

Whether the CALLER may change this organization's own settings — the org:manage permission that PATCH /organization/{id} requires, and the organization neither staff-suspended nor in its deletion grace period. Server-computed, and false wherever can_delete is for lack of a member context; it never overstates.

can_require_mfaboolean

Whether the CALLER may turn mfa_required ON right now: can_manage, from an interactive session that would itself pass the check it is about to create. false — with the reason in can_require_mfa_reason — when switching it on would lock the caller out of this organization. The PATCH refuses that regardless with 409 mfa_setup_required. Turning it OFF is not governed by this field; it needs a step-up.

can_require_mfa_reasonstring,null

A sentence saying why can_require_mfa is false for a caller who can otherwise manage the organization. null otherwise.

can_restoreboolean

Whether the CALLER may cancel a scheduled deletion: the org:manage permission, and only while purge_after is still ahead. Server-computed, like can_delete, and false for the same reasons — no member context (the org switcher list, the staff console) — plus once the window has closed. Read purge_after to tell "too late" from "not yours to undo".

created_atstring · date-time
deletion_scheduled_atstring,null · date-time

Set when a deletion has been scheduled (DELETE /organization/{id}). The organization is read-only until purge_after. Null otherwise.

idstring

Organization id (org_…) — the value for X-Organization-Id.

logostring,null · uri

Public URL of the logo image, or null.

mfa_requiredboolean

Whether members must hold a second factor to act in this organization. false by default, for existing and new organizations alike. When true, a signed-in session that has not shown a second factor — no TOTP challenge at login, not a passkey sign-in, no factor enrolled since — is refused on every organization-scoped route, reads included, with 403 mfa_setup_required (error.details.has_second_factor says whether the person already has one and only needs to sign in with it). Exempt: org API tokens, Elaichi staff impersonation sessions, and a session signed in through THIS organization's own SSO connection. MCP connections made before it was switched on, or from a session without a factor, are refused too until the person connects again. Turning it OFF only lifts that requirement: a member who set up an authenticator app of their own is still challenged for it at every non-passkey sign-in, because the factor belongs to the member and no organization setting can switch it off. Changed with PATCH /organization/{id} (org:manage, interactive session only).

namestring
planstring

The stored plan: gold, black, or none when locked. This is not the same as the effective entitlement — read GET /organization/{id}/entitlements before gating a feature on it.

purge_afterstring,null · date-time

When a scheduled deletion becomes permanent — 30 days after deletion_scheduled_at. Null unless scheduled.

regionstring,null

Data location fixed at creation: us/eu pin a hard jurisdiction, apac is a placement hint.

settingsRecord<string, any>

Free-form org settings. PATCH /organization/{id} REPLACES this object wholesale.

slugstring

Immutable after creation.

trial_ends_atstring,null · date-time
trial_indefinite_atstring,null · date-time

When staff granted an indefinite trial, or null. Unlocked with no end date: no countdown, no expiry email, billing still reachable.

updated_atstring · date-time
curl -X PATCH 'https://api.elaichi.ai/organization/<id>' \
  -H 'Authorization: Bearer $ELAICHI_API_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"name":"your_name","settings":{},"allow_staff_impersonation":true,"mfa_required":true}'
const body = {
  "name": "your_name",
  "settings": {},
  "allow_staff_impersonation": true,
  "mfa_required": true
};

const response = await fetch('https://api.elaichi.ai/organization/<id>', {
  method: 'PATCH',
  headers: {
    'Authorization': 'Bearer ' + process.env.ELAICHI_API_TOKEN,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify(body),
});

const data = await response.json();
console.log(data);
import os
import requests

url = "https://api.elaichi.ai/organization/<id>"
headers = {
    "Authorization": f"Bearer {os.environ['ELAICHI_API_TOKEN']}",
    "Content-Type": "application/json",
}
payload = {
    "name": "your_name",
    "settings": {},
    "allow_staff_impersonation": True,
    "mfa_required": True
}

response = requests.patch(url, headers=headers, json=payload)
print(response.json())