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

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

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

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