Umgebungsrolle erstellen

POST /v1/roles · Berechtigung roles:write

Erstellt eine Rolle im Rollenkatalog der Umgebung. Die Antwort enthält ein ETag; der Schreibvorgang wird als role.created protokolliert. Idempotency-Key ist optional.

Anfrage

Feld Typ Pflicht Beschreibung
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: im Self-Service kann nur ein Mitglied mit der Organisations-Administratorrolle (org_admin_role_id) sie zuweisen, und die Zuordnung einer externen Gruppe zu ihr erfordert roles:write und Genehmigung.
assignable_in_self_service boolean nein Standardmäßig true, auch für eine privilegierte Rolle.

Antwort

201 Created mit der Rolle.

{
  "id": "rol_01j9xr7s1t2w6x8y0z2a4b6c8e",
  "organization_id": null,
  "key": "support",
  "name": "Support",
  "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
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.
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/roles" \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"key":"support","name":"Support"}'