Organisationsrolle erstellen

POST /v1/organizations/{org_id}/roles · Berechtigung roles:write

Erstellt eine benutzerdefinierte Rolle, die nur in dieser Organisation existiert. Organisationsrollen erfordern das Tarif-Feature org_custom_roles, können nicht privilegiert sein und können nicht erstellt werden, solange die Liste der für Organisationsrollen zulässigen Berechtigungen der Umgebung leer ist. Die Antwort enthält ein ETag; der Schreibvorgang wird als role.created protokolliert. Idempotency-Key ist optional.

Anfrage

Feld Typ Pflicht Beschreibung
org_id path ja Organisations-ID (org_…).
key string ja Kleinbuchstaben, Ziffern, _ und -; 1–64 Zeichen; im Geltungsbereich eindeutig und unveränderlich.
name string ja Anzeigename, bis zu 128 Zeichen.
description string nein Bis zu 1024 Zeichen.
is_privileged boolean nein Kennzeichnet eine privilegierte Rolle (für Organisationsrollen nicht zulässig).
assignable_in_self_service boolean nein Standardmäßig true.

Antwort

201 Created mit der Rolle.

{
  "id": "rol_01j9xr7s1t2w6x8y0z2a4b6c8e",
  "organization_id": "org_01j9xk3m7q8r2s4t6v8w0y2z4a",
  "key": "billing-admin",
  "name": "Billing admin",
  "description": "",
  "is_privileged": false,
  "assignable_in_self_service": true,
  "permission_ids": [],
  "created_at": "2026-10-12T09:31:00.123456Z",
  "updated_at": "2026-10-12T09:31:00.123456Z",
  "version": 1
}

Fehler

HTTP code Wann
404 not_found Die Organisation existiert in dieser Umgebung nicht.
403 org_custom_roles_disabled Organisationsrollen sind in dieser Umgebung deaktiviert.
403 plan_feature_unavailable Der Tarif enthält keine Organisationsrollen (Business und höher).
409 role_key_conflict Im Geltungsbereich existiert bereits eine Rolle mit diesem key.
409 role_limit_reached Das Limit von 1.000 Umgebungsrollen bzw. 50 Rollen je Organisation ist erreicht.
422 validation_failed Ein Feld fehlt oder ist ungültig, oder is_privileged ist true.
401 unauthenticated Die Anmeldeinformation fehlt, ist ungültig oder widerrufen.
403 insufficient_permissions Die Anmeldeinformation hat nicht die erforderliche Berechtigung.
429 rate_limited Das Ratenlimit wurde überschritten; nach der Dauer von Retry-After erneut versuchen.
503 service_unavailable Eine Abhängigkeit ist vorübergehend nicht verfügbar; nach der Dauer von Retry-After erneut versuchen.

Beispiel

curl -i -X POST "https://api.eu.keenauth.com/v1/organizations/org_01j9xk3m7q8r2s4t6v8w0y2z4a/roles" \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"key":"billing-admin","name":"Billing admin"}'