# Obtenir un rôle de l'organisation

`GET /fapi/v1/organizations/{org_id}/roles/{role_id}` · appelé depuis l'hôte de connexion de l'environnement

Renvoie un rôle de l'organisation, ou un rôle d'environnement que les administrateurs de l'organisation peuvent attribuer. Nécessite le cookie `__Host-idp_session` de l'utilisateur authentifié ; si le cookie est absent, expiré ou révoqué, renvoie `401 unauthenticated`. Une application de première partie sur une autre origine peut à la place envoyer son jeton d'accès à l'API frontale (`Authorization: DPoP <token>` avec une preuve DPoP ; voir [Jeton d'accès à l'API frontale](/docs/api/fapi/front-api-token)). L'utilisateur doit être membre actif de l'organisation avec l'autorisation `idp_roles:manage`. Un utilisateur qui n'est pas membre reçoit `404 not_found`, afin que l'existence de l'organisation ne soit pas divulguée ; un membre sans cette autorisation reçoit `403 insufficient_permissions`. Les rôles d'organisation doivent être activés pour l'environnement et inclus dans son offre.

## Requête

En-têtes :

| En-tête | Obligatoire | Description |
| --- | --- | --- |
| `Idp-Client` | oui | Identifiant du SDK. |

`org_id` : l'identifiant de l'organisation (`org_…`). `role_id` : l'identifiant du rôle (`rol_…`).

Pas de corps.

## Réponse

`200 OK` avec un en-tête `ETag` (`"<version>"`) :

| Champ | Type | Description |
| --- | --- | --- |
| `id` | chaîne | Identifiant du rôle (`rol_…`). |
| `organization_id` | chaîne ou null | Identifiant de l'organisation (`org_…`) ; `null` pour un rôle d'environnement proposé à l'attribution dans l'organisation (lecture seule ici). |
| `key` | chaîne | Clé du rôle ; unique dans l'organisation et parmi les rôles d'environnement ; ne change jamais. |
| `name` | chaîne | Nom d'affichage. |
| `description` | chaîne | Description ; vide si non définie. |
| `is_privileged` | booléen | Indique si le rôle accorde des autorisations d'administration. |
| `assignable_in_self_service` | booléen | Indique si les administrateurs de l'organisation peuvent attribuer le rôle. |
| `permission_ids` | chaîne[] | Identifiants d'autorisation (`perm_…`). |
| `created_at` | chaîne | RFC 3339, UTC. |
| `updated_at` | chaîne | RFC 3339, UTC. |
| `version` | entier | Version actuelle ; également envoyée dans l'en-tête `ETag` (`"<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
}
```

## Erreurs

| Statut | Code | Quand |
| --- | --- | --- |
| 401 | `unauthenticated` | Aucun cookie de session valide. |
| 403 | `insufficient_permissions` | L'utilisateur ne dispose pas de `idp_roles:manage` dans l'organisation. |
| 403 | `plan_feature_unavailable` | L'offre de l'environnement n'inclut pas les rôles d'organisation (`feature`, `required_plan`). |
| 403 | `org_custom_roles_disabled` | Les rôles d'organisation sont désactivés pour l'environnement. |
| 404 | `not_found` | Aucune organisation ou aucun rôle correspondant pour cet utilisateur (un identifiant inconnu, mal formé ou étranger reçoit la même réponse). |
| 503 | `service_unavailable` | Temporairement indisponible ; réessayer après `Retry-After`. |

## Exemple

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