Eine Organisationsrolle abrufen

GET /fapi/v1/organizations/{org_id}/roles/{role_id} · wird vom Anmelde-Host der Umgebung aufgerufen

Gibt eine Rolle der Organisation oder eine Umgebungsrolle zurück, die Organisationsadministratoren zuweisen dürfen. Erforderlich ist das Cookie __Host-idp_session des authentifizierten Benutzers; fehlt das Cookie, ist es abgelaufen oder widerrufen, wird 401 unauthenticated zurückgegeben. Eine Erstanbieter-Anwendung auf einem anderen Ursprung kann stattdessen ihr Front-API-Zugriffstoken senden (Authorization: DPoP <token> mit einem DPoP-Nachweis; 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, damit 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 in deren Tarif enthalten sein.

Anfrage

Header:

Header Erforderlich Beschreibung
Idp-Client ja SDK-Kennung.

org_id: die Organisations-ID (org_…). role_id: die Rollen-ID (rol_…).

Kein Body.

Antwort

200 OK mit einem ETag-Header ("<version>"):

Feld Typ Beschreibung
id string Rollen-ID (rol_…).
organization_id string oder null Organisations-ID (org_…); null bei einer Umgebungsrolle, die in der Organisation zur Zuweisung angeboten wird (hier nur lesbar).
key string Rollenschlüssel; innerhalb der Organisation und unter den Umgebungsrollen eindeutig; ändert sich nie.
name string Anzeigename.
description string Beschreibung; leer, wenn nicht gesetzt.
is_privileged boolean Gibt an, ob die Rolle administrative Berechtigungen gewährt.
assignable_in_self_service boolean Gibt an, ob Organisationsadministratoren die Rolle zuweisen dürfen.
permission_ids string[] Berechtigungs-IDs (perm_…).
created_at string RFC 3339, UTC.
updated_at string RFC 3339, UTC.
version integer Aktuelle Version; wird außerdem als ETag-Header gesendet ("<version>"). 
{
  "id": "rol_01jbz6x8kq3m2n4p5r6s7t8v9w",
  "organization_id": "org_01jbz6x8kq3m2n4p5r6s7t8v9a",
  "key": "auditor",
  "name": "Auditor",
  "description": "Read-only access to reports",
  "is_privileged": false,
  "assignable_in_self_service": true,
  "permission_ids": ["perm_01jbz6x8kq3m2n4p5r6s7t8v9b"],
  "created_at": "2026-10-28T09:30:00Z",
  "updated_at": "2026-10-28T09:30:00Z",
  "version": 1
}

Fehler

Status Code Wann
401 unauthenticated Kein gültiges Sitzungs-Cookie.
403 insufficient_permissions Der Benutzer besitzt idp_roles:manage in der Organisation nicht.
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).
503 service_unavailable Vorübergehend nicht verfügbar; nach Retry-After erneut versuchen.

Beispiel

curl https://example.keenauth.app/fapi/v1/organizations/org_01jbz6x8kq3m2n4p5r6s7t8v9a/roles/rol_01jbz6x8kq3m2n4p5r6s7t8v9w \
  -H "Idp-Client: my-app/1.0.0 (node/22.0.0)" \
  -b cookies.txt