Create organization

POST /organization

Creates an organization and makes the caller its first member, holding the immutable Org Owner role; the predefined role set is seeded at the same time. Needs an interactive browser session: an org API token is refused with 403, because a token scoped to one organization must not create another. Also needs public signup to be enabled for the service; otherwise 403 `signup_disabled`.

Request Body

namestring

referral_codestring

Optional referral code, for tracking only. Whitespace is trimmed, a blank value is treated as absent, and it is stored upper-cased. Recorded once at creation; not returned by this API and not editable.

regionstring

Data location, fixed at creation: eu and us pin the organization's data to that jurisdiction, apac is a placement hint. It cannot be changed afterwards.

Possible values:

useuapac

signup_sourceobject

Optional attribution for where the signup came from, for tracking only. Every field is optional. Malformed input is dropped, never a 400: unknown keys, non-string or blank values, and a referrer_host that is not a hostname are ignored. Values are cut to 100 characters; referrer_host is reduced to a lowercase hostname (a full URL is accepted and stripped to its host). Recorded once at creation; not returned by this API and not editable.

refstring

referrer_hoststring

utm_campaignstring

utm_contentstring

utm_mediumstring

utm_sourcestring

utm_termstring

slugstring

Lowercase alphanumeric with hyphens. Generated from the name when omitted.

Response Body

allow_staff_impersonationboolean

Whether Elaichi support may sign in as this organization's members to help them. true by default. When false, every request made through such a support session 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, then plan_single_user (Personal admits only the primary owner). null when connecting is open.

Possible values:

blockedpending_deletionno_planplan_single_usernull

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, has no active plan, or is on Personal and the caller is not its primary owner. 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. Server-computed, so branch on this rather than inspecting roles. Always false on rows that have no member context to compute it from, such as the organization list GET /organization. It never overstates: trust it when true, and read GET /user/me or GET /organization/{id} (both compute it) when you need it for a list row.

can_manageboolean

Whether the caller may change this organization's settings: the org:manage permission that PATCH /organization/{id} requires, and the organization is neither suspended nor in its deletion grace period. Server-computed, and false wherever can_delete is false 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 on rows with no member context. 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. When true, a signed-in session that has not shown a second factor (no TOTP challenge at login, no 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 support 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 until the person connects again. Turning it off only lifts the organization requirement: a member who set up an authenticator app of their own is still challenged for it at every non-passkey sign-in. Changed with PATCH /organization/{id} (org:manage, interactive session only).

namestring

planstring

The stored plan: personal, gold, black, or none while on hold. 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

Set when Elaichi granted this organization an indefinite trial, otherwise null. Unlocked with no end date: no countdown, no expiry email, billing still reachable.

updated_atstring · date-time

curl -X POST 'https://api.elaichi.ai/organization' \
  -H 'Authorization: Bearer $ELAICHI_API_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"name":"your_name","slug":"your_slug","region":"us","referral_code":"your_referral_code","signup_source":{}}'

const body = {
  "name": "your_name",
  "slug": "your_slug",
  "region": "us",
  "referral_code": "your_referral_code",
  "signup_source": {}
};

const response = await fetch('https://api.elaichi.ai/organization', {
  method: 'POST',
  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"
headers = {
    "Authorization": f"Bearer {os.environ['ELAICHI_API_TOKEN']}",
    "Content-Type": "application/json",
}
payload = {
    "name": "your_name",
    "slug": "your_slug",
    "region": "us",
    "referral_code": "your_referral_code",
    "signup_source": {}
}

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