# 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](/docs/api/fapi/front-api-token)). 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>"`). |

```json
{
  "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

```bash
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
```