---
title: "Create an organization (multi-tenancy)"
method: POST
path: "/api/v1/organizations"
tags: ["Multi-tenancy"]
---

# Create an organization (multi-tenancy)

`POST /api/v1/organizations`

## Request

- Base URL: `https://legal.nexusquantum.legal`
- URL: `https://legal.nexusquantum.legal/api/v1/organizations`
- Auth: HTTP bearer

Creates an organization and promotes the current key to `role: master`. Only keys with `role: solo` (default) can create orgs. `role: child` keys receive 403. A `master` key that already belongs to another org receives 409 `ALREADY_MASTER`.

Use case: distributor / partner that needs to serve N end clients with separate keys + usage rollup. After creating the org, use `POST /api/v1/organizations/{id}/keys` to generate sub-keys (`role: child`).

## Request body

- object
  - `name` string, required
  - `description` string

## Response `201`

Org created. The authenticated key is promoted to master.

- object
  - `organization` object
    - `id` string, uuid
    - `name` string
    - `description` string, nullable
    - `created_at` string, date-time
  - `masterKeyId` string, uuid

## Other responses

- `403`: A child role cannot create orgs.
- `409`: Key is already master of another org.
- `422`: Limit of 5 orgs per user reached.

---

[API](https://skmtc.dev/nexusquantum/apis/nexus-legal-api.md) · [All operations](https://skmtc.dev/nexusquantum/apis/nexus-legal-api/llms.txt) · [OpenAPI document](https://skmtc.dev/nexusquantum/apis/nexus-legal-api/revisions/4084d8d4eb0b?raw)