# Establecer permisos del rol

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

Reemplaza el conjunto de permisos de un rol de la organización. Solo pueden usarse los permisos que el entorno permite para los roles de la organización, y los administradores solo pueden conceder los permisos que ellos mismos poseen. Aquí no se pueden crear permisos ni API. 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. |
| `Origin` | sí | Debe ser exactamente `https://<host de inicio de sesión>`. |
| `Content-Type` | con cuerpo | `application/json`. |
| `If-Match` | no | `"<version>"` del rol tal como se leyó por última vez; si el rol ha cambiado desde entonces, devuelve `412 precondition_failed` y nada cambia. |

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

Cuerpo:

| Campo | Obligatorio | Descripción |
| --- | --- | --- |
| `permission_ids` | sí | El conjunto completo, con un máximo de 100 identificadores de permisos (`perm_…`); `[]` elimina todos. |

## Respuesta

`200 OK` con un nuevo `ETag`; el cuerpo es el rol (consulte [Obtener un rol de la organización](./get)).

## Errores

| Estado | Código | Cuándo |
| --- | --- | --- |
| 401 | `unauthenticated` | No hay una cookie de sesión válida. |
| 403 | `origin_not_allowed` | `Origin` falta o es incorrecto. |
| 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. |
| 403 | `role_not_assignable` | El rol, o el nuevo conjunto, concede un permiso que el usuario no posee, o la propia membresía del usuario tiene asignado el rol. |
| 404 | `not_found` | No existe la organización o el rol de la organización para este usuario; un rol del entorno, un identificador desconocido, mal formado o ajeno recibe la misma respuesta. |
| 409 | `organization_pending_deletion` | La organización está programada para su eliminación. |
| 412 | `precondition_failed` | `If-Match` no indica la versión actual, o el rol cambió mientras se procesaba la solicitud. |
| 422 | `permission_not_allowed` | Un permiso no está permitido para los roles de la organización. |
| 422 | `permission_reserved` | Un permiso está reservado para la plataforma. |
| 422 | `validation_failed` | La lista no es válida o es demasiado larga. |
| 503 | `service_unavailable` | No disponible temporalmente; reintente después de `Retry-After`. |

## Ejemplo

```bash
curl -X PUT https://example.keenauth.app/fapi/v1/organizations/org_01jbz6x8kq3m2n4p5r6s7t8v9a/roles/rol_01jbz6x8kq3m2n4p5r6s7t8v9w/permissions \
  -H "Idp-Client: my-app/1.0.0 (node/22.0.0)" \
  -H "Origin: https://example.keenauth.app" \
  -H "Content-Type: application/json" \
  -b cookies.txt \
  -d '{"permission_ids":["perm_01jbz6x8kq3m2n4p5r6s7t8v9b"]}'
```