Actualizar un rol de organización
PATCH /fapi/v1/organizations/{org_id}/roles/{role_id} · llamado desde el host de inicio de sesión del entorno
Cambia el nombre o la descripción de un rol de organización (merge patch de JSON, RFC 7396). Los roles del entorno no se pueden cambiar aquí. 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 de primera parte en otro origen puede enviar en su lugar su token de acceso a la API frontal (Authorization: DPoP <token> con una prueba DPoP; consulte Token de acceso de 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, para no revelar la existencia de la organización; un miembro sin el permiso recibe 403 insufficient_permissions. Los roles de 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://<sign-in host>. |
Content-Type |
con un cuerpo | application/json o application/merge-patch+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 (al menos un campo):
| Campo | Obligatorio | Descripción |
|---|---|---|
name |
no | Nuevo nombre visible. |
description |
no | Nueva descripción. |
Respuesta
200 OK con un nuevo ETag; el cuerpo es el rol (consulte Obtener un rol de organización).
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 organización (feature, required_plan). |
| 403 | org_custom_roles_disabled |
Los roles de organización están desactivados para el entorno. |
| 403 | role_not_assignable |
El rol concede un permiso que el usuario no posee, o la propia membresía del usuario lo incluye. |
| 404 | not_found |
No existe tal organización o rol de 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 | validation_failed |
Un campo no es válido, o el patch está vacío (empty_patch). |
| 503 | service_unavailable |
No disponible temporalmente; reintente después de Retry-After. |
Ejemplo
curl -X PATCH https://example.keenauth.app/fapi/v1/organizations/org_01jbz6x8kq3m2n4p5r6s7t8v9a/roles/rol_01jbz6x8kq3m2n4p5r6s7t8v9w \
-H "Idp-Client: my-app/1.0.0 (node/22.0.0)" \
-H "Origin: https://example.keenauth.app" \
-H "Content-Type: application/merge-patch+json" \
-H 'If-Match: "1"' \
-b cookies.txt \
-d '{"name":"Auditors"}'