Organisationsrollen auflisten

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

Gibt die eigenen Rollen der Organisation und die Umgebungsrollen zurück, die Organisationsadministratoren zuweisen dürfen, sortiert nach Bezeichner. 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_…).

Query-Parameter:

Parameter Erforderlich Beschreibung
limit nein Seitengröße, 1 bis 100; Standard 20.
after nein Der next_after-Wert der vorherigen Seite.

Kein Body.

Antwort

200 OK:

Feld Typ Beschreibung
data[] object[] Rollen mit den Feldern, die unter Eine Organisationsrolle abrufen beschrieben sind.
next_after string Als after für die nächste Seite übergeben; auf der letzten Seite nicht vorhanden. 
{
  "data": [
    {
      "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
400 invalid_cursor after ist keine Rollen-ID aus einer vorherigen Seite.
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).
422 validation_failed limit liegt außerhalb des zulässigen Bereichs.
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?limit=20 \
  -H "Idp-Client: my-app/1.0.0 (node/22.0.0)" \
  -b cookies.txt