# Eine Organisation erstellen

`POST /v1/organizations` · Berechtigung `organizations:write`

Erstellt eine Organisation in der Umgebung. Die Antwort enthält einen `ETag`. Ein Ereignis `organization.created` wird veröffentlicht und die Änderung wird im Audit-Log der Management-API protokolliert.

## Anfrage

| Feld | Typ | Pflicht | Beschreibung |
|---|---|---|---|
| `Idempotency-Key` | header | nein | Optional. 16–64 Zeichen `[A-Za-z0-9_-]`; die Wiederholung desselben Schlüssels mit derselben Anfrage liefert dieselbe Antwort. |
| `name` | string | ja | Anzeigename, 1–256 Zeichen, ohne Steuerzeichen. |
| `slug` | string | nein | 3–64 Zeichen `a-z`, `0-9` und einzelne Bindestriche; in der Umgebung eindeutig. Wird aus dem Namen abgeleitet, wenn er fehlt. |
| `external_id` | string \| null | nein | Ihr eigener Bezeichner, bis zu 255 Zeichen; in der Umgebung eindeutig. `null` entfernt ihn. |
| `metadata` | object \| null | nein | JSON-Objekt, höchstens 16 KiB, 5 Ebenen und 100 Schlüssel auf oberster Ebene. Wird nur von der Management-API zurückgegeben. |
| `brand_color` | string \| null | nein | Markenfarbe `#RRGGBB`; wird in Großbuchstaben gespeichert. `null` entfernt sie. |
| `max_memberships` | integer \| null | nein | Obergrenze für Mitgliedschaften, mindestens 1; `null` bedeutet unbegrenzt. |
| `default_zoneinfo` | string \| null | nein | Standard-IANA-Zeitzone (zum Beispiel `Europe/Istanbul`), die für Registrierung, Einladung, JIT-SSO und SCIM im Organisationskontext verwendet wird, wenn Browser oder IdP keine liefern. `null` entfernt sie (der Standard der Umgebung gilt). |

Anfragetext:

```json
{
  "name": "Acme Corp",
  "slug": "acme",
  "external_id": "crm-4821",
  "metadata": {
    "tier": "gold"
  },
  "brand_color": "#1F6FEB"
}
```

## Antwort

`201 Created` mit der neuen Organisation.

```json
{
  "id": "org_01j9xk3m7q8r2s4t6v8w0y2z4a",
  "name": "Acme Corp",
  "slug": "acme",
  "external_id": "crm-4821",
  "status": "active",
  "metadata": {
    "tier": "gold"
  },
  "brand_color": "#1F6FEB",
  "max_memberships": null,
  "default_zoneinfo": null,
  "created_via": "admin_api",
  "disabled_at": null,
  "deletion_requested_at": null,
  "deletion_due_at": null,
  "created_at": "2026-10-12T09:30:00.123456Z",
  "updated_at": "2026-10-12T09:30:00.123456Z",
  "version": 1
}
```

## Fehler

| HTTP | Code | Wann |
|---|---|---|
| 400 | `unknown_field` | Der Anfragetext enthält ein Feld, das nicht im Schema vorkommt oder schreibgeschützt ist (`id`, `status` …). |
| 401 | `unauthenticated` | Die Anmeldedaten fehlen, sind ungültig oder widerrufen. |
| 403 | `insufficient_permissions` | Den Anmeldedaten fehlt die erforderliche Berechtigung. |
| 403 | `quota_exceeded` | Das Organisationslimit des Tarifs der Umgebung (`organizations_per_environment_max`) ist erreicht. |
| 409 | `slug_taken` | Der Slug wird bereits von einer anderen Organisation verwendet. |
| 409 | `slug_reserved` | Der Slug ist ein reserviertes Wort oder der frühere Slug einer anderen Organisation (90 Tage reserviert). |
| 409 | `external_id_taken` | Die `external_id` wird bereits von einer anderen Organisation verwendet. |
| 422 | `validation_failed` | Ein Feld ist ungültig (`name`, `slug`, `external_id`, `metadata`, `brand_color`, `max_memberships`, `default_zoneinfo`). |
| 422 | `idempotency_key_reuse` | Der `Idempotency-Key` wurde bereits mit einer anderen Anfrage verwendet. |
| 429 | `rate_limited` | Das Rate-Limit wurde überschritten; wiederholen Sie die Anfrage nach Ablauf der Zeit aus `Retry-After`. |
| 503 | `service_unavailable` | Eine Abhängigkeit ist vorübergehend nicht verfügbar; wiederholen Sie die Anfrage nach Ablauf der Zeit aus `Retry-After`. |

## Beispiel

```bash
curl -X POST "https://api.eu.keenauth.com/v1/organizations" \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Acme Corp","slug":"acme"}'
```