Organisationsrolle erstellen
POST /fapi/v1/organizations/{org_id}/roles · wird vom Anmeldehost der Umgebung aufgerufen
Erstellt eine Rolle in der Organisation, zunächst ohne Berechtigungen; Berechtigungen fügen Sie mit Berechtigungen der Rolle festlegen hinzu. Eine Organisation kann höchstens 50 Rollen haben. Erforderlich ist das Cookie __Host-idp_session des authentifizierten Benutzers; fehlt das Cookie, ist es abgelaufen oder widerrufen, antwortet der Endpunkt mit 401 unauthenticated. Eine First-Party-Anwendung auf einer anderen Origin kann stattdessen ihr Front-API-Zugriffstoken senden (Authorization: DPoP <token> mit einem DPoP-Proof; siehe Front-API-Zugriffstoken). Der Benutzer muss aktives Mitglied der Organisation sein und die Berechtigung idp_roles:manage besitzen. Ein Benutzer, der kein Mitglied ist, erhält 404 not_found, sodass die Existenz der Organisation nicht offengelegt wird; ein Mitglied ohne die Berechtigung erhält 403 insufficient_permissions. Organisationsrollen müssen für die Umgebung aktiviert und im Tarif enthalten sein.
Anfrage
Header:
| Header | Pflicht | Beschreibung |
|---|---|---|
Idp-Client |
ja | SDK-Kennung. |
Origin |
ja | Muss genau https://<Anmeldehost> sein. |
Content-Type |
ja | application/json. |
org_id: die Organisations-ID (org_…).
Body:
| Feld | Pflicht | Beschreibung |
|---|---|---|
key |
ja | Schlüssel der Rolle; in der Organisation und unter den Rollen der Umgebung eindeutig; kann später nicht geändert werden. |
name |
ja | Anzeigename. |
description |
nein | Beschreibung. |
Antwort
201 Created mit den Headern Location und ETag; der Body ist die Rolle (siehe Eine Organisationsrolle abrufen).
Fehler
| Status | Code | Wann |
|---|---|---|
| 401 | unauthenticated |
Kein gültiges Sitzungs-Cookie. |
| 403 | origin_not_allowed |
Origin fehlt oder ist falsch. |
| 403 | insufficient_permissions |
Dem Benutzer fehlt idp_roles:manage in der Organisation. |
| 403 | plan_feature_unavailable |
Der Tarif der Umgebung enthält keine Organisationsrollen (feature, required_plan). |
| 403 | org_custom_roles_disabled |
Organisationsrollen sind für die Umgebung deaktiviert. |
| 404 | not_found |
Für diesen Benutzer existiert keine solche Organisation oder Rolle (eine unbekannte, fehlerhafte oder fremde ID führt zur selben Antwort). |
| 409 | role_key_conflict |
Der Schlüssel ist bereits in der Organisation oder von einer Rolle der Umgebung vergeben. |
| 409 | role_limit_reached |
Die Organisation hat bereits 50 Rollen. |
| 409 | organization_pending_deletion |
Die Organisation ist zur Löschung vorgesehen. |
| 422 | validation_failed |
Ein Feld fehlt oder ist ungültig; errors[] benennt es. |
| 503 | service_unavailable |
Vorübergehend nicht verfügbar; wiederholen Sie die Anfrage nach Retry-After. |
Beispiel
curl -X POST https://example.keenauth.app/fapi/v1/organizations/org_01jbz6x8kq3m2n4p5r6s7t8v9a/roles \
-H "Idp-Client: my-app/1.0.0 (node/22.0.0)" \
-H "Origin: https://example.keenauth.app" \
-H "Content-Type: application/json" \
-b cookies.txt \
-d '{"key":"auditor","name":"Auditor"}'