Listar roles de la organización

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

Devuelve los roles propios de la organización y los roles del entorno que los administradores de la organización pueden asignar, ordenados por identificador. 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_…).

Parámetros de consulta:

Parámetro Obligatorio Descripción
limit no Tamaño de página, de 1 a 100; por defecto 20.
after no El valor next_after de la página anterior.

Sin cuerpo.

Respuesta

200 OK:

Campo Tipo Descripción
data[] object[] Roles, con los campos descritos en Obtener un rol de la organización.
next_after string Envíelo como after para la página siguiente; no aparece en la última página. 
{
  "data": [
    {
      "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
400 invalid_cursor after no es un identificador de rol de una página anterior.
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).
422 validation_failed limit está fuera de rango.
503 service_unavailable No disponible temporalmente; reintente después de Retry-After.

Ejemplo

curl https://example.keenauth.app/fapi/v1/organizations/org_01jbz6x8kq3m2n4p5r6s7t8v9a/roles?limit=20 \
  -H "Idp-Client: my-app/1.0.0 (node/22.0.0)" \
  -b cookies.txt