Obtener un rol de la organización

GET /fapi/v1/organizations/{org_id}/roles/{role_id} · llamado desde el host de inicio de sesión del entorno

Devuelve un rol de la organización o un rol del entorno que los administradores de la organización pueden asignar. Requiere la cookie __Host-idp_session del usuario autenticado; si la cookie falta, ha caducado o ha sido revocada, devuelve 401 unauthenticated. Una aplicación propia en otro origen puede, en su lugar, enviar su token de acceso a la API frontal (Authorization: DPoP <token> con una prueba DPoP; consulte Token de acceso a la API frontal). El usuario debe ser miembro activo de la organización con el permiso idp_roles:manage. Un usuario que no es miembro recibe 404 not_found, de modo que no se revela la existencia de la organización; un miembro sin el permiso recibe 403 insufficient_permissions. Los roles de la organización deben estar habilitados para el entorno e incluidos en su plan.

Solicitud

Encabezados:

Encabezado	Obligatorio	Descripción
`Idp-Client`	sí	Identificador del SDK.

org_id: el identificador de la organización (org_…). role_id: el identificador del rol (rol_…).

Sin cuerpo.

Respuesta

200 OK con un encabezado ETag ("<version>"):

Campo	Tipo	Descripción
`id`	string	Identificador del rol (`rol_…`).
`organization_id`	string o null	Identificador de la organización (`org_…`); `null` para un rol del entorno ofrecido para su asignación en la organización (solo lectura aquí).
`key`	string	Clave del rol; única en la organización y entre los roles del entorno; nunca cambia.
`name`	string	Nombre para mostrar.
`description`	string	Descripción; vacía cuando no se ha definido.
`is_privileged`	boolean	Indica si el rol concede permisos administrativos.
`assignable_in_self_service`	boolean	Indica si los administradores de la organización pueden asignar el rol.
`permission_ids`	string[]	Identificadores de permisos (`perm_…`).
`created_at`	string	RFC 3339, UTC.
`updated_at`	string	RFC 3339, UTC.
`version`	integer	Versión actual; también se envía en el encabezado `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
}

Errores

Estado	Código	Cuándo
401	`unauthenticated`	No hay una cookie de sesión válida.
403	`insufficient_permissions`	El usuario no tiene `idp_roles:manage` en la organización.
403	`plan_feature_unavailable`	El plan del entorno no incluye roles de la organización (`feature`, `required_plan`).
403	`org_custom_roles_disabled`	Los roles de la organización están desactivados para el entorno.
404	`not_found`	No existe la organización o el rol para este usuario (un identificador desconocido, mal formado o ajeno recibe la misma respuesta).
503	`service_unavailable`	No disponible temporalmente; reintente después de `Retry-After`.

Ejemplo

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