Create a new organisation — a full workspace: the tenant, its 1:1 organisation, the creating user’s record and their ACTIVE membership are bootstrapped together, then the default roles are seeded (with the caller assigned Admin)
POST/api/organisations
Create a new organisation — a full workspace: the tenant, its 1:1 organisation, the creating user’s record and their ACTIVE membership are bootstrapped together, then the default roles are seeded (with the caller assigned Admin). The endpoint is IDEMPOTENT PER SLUG FOR ITS CREATOR (PLT-960): when a prior attempt bootstrapped the tenant but failed before role seeding, retrying the same slug as the same user RESUMES that tenant — the 201 carries the original tenant id and the PERSISTED organisation record (a changed name in the retry body is not applied) and seeding is re-run. Seeding is serialized per tenant, so concurrent same-slug submissions are safe: the loser resumes or receives the member-aware 409.
Request
Responses
- 201
- 400
- 401
- 403
- 409
- 500
Successful response
Malformed JSON body (error only), or a body failing schema validation (name/slug — carries the Zod issues in details).
Unauthorized — authentication credentials are missing or invalid
Forbidden — the x-act-as-org selector named an organisation the caller is not an ACTIVE member of (or the caller lacks the required permission).
The slug is already taken. Two messages distinguish the cases: a tenant the caller is NOT in returns the generic "An organisation with this slug already exists"; the caller’s own FULLY-PROVISIONED tenant returns "… — you are already a member of it" (switch into it instead of re-creating). The caller’s own HALF-PROVISIONED tenant never 409s — it resumes as a 201.
Provisioning failed — including a non-slug integrity violation inside the bootstrap (deliberately NOT reported as a slug conflict) and Directory role-seeding failures. The flow is retryable: a retry resumes the half-provisioned tenant rather than burning the slug.