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). 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>"). 
{
  "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

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