# Establecer los roles de un miembro

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

Reemplaza los roles de una membresía por un conjunto completo, para una pantalla de perfil de organización. El conjunto abarca solo los roles que usted puede ver en esta organización: sus propios roles y los roles del entorno abiertos a los administradores de la organización. Los demás roles del miembro se mantienen. Un conjunto vacío elimina todos los roles que usted puede ver; si el miembro se queda sin ninguno, se le asigna el rol predeterminado de la organización.

Requiere la cookie `__Host-idp_session` del usuario autenticado con un `Origin` exacto, o un token de acceso de la API frontal de una aplicación propia (`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 un miembro activo de la organización con el permiso `idp_members:update_roles`. Un usuario que no es miembro recibe `404 not_found`; un miembro sin el permiso recibe `403 insufficient_permissions`.

Reglas de asignación:

- Cada permiso de cada rol que asigne debe ser uno que usted mismo posea.
- Solo un miembro que tenga el rol de administrador puede asignar un rol privilegiado.
- No puede cambiar sus propios roles.
- El último administrador activo no puede perder el rol de administrador (`409 last_org_admin`).

Con `@keenauth/js`: `await keenauth.organizations.setMemberRoles(orgId, membershipId, [roleId], { expectedVersion: 3 })`.

## Solicitud

Encabezados:

| Encabezado | Obligatorio | Descripción |
| --- | --- | --- |
| `Idp-Client` | sí | Identificador del SDK. |
| `Origin` | sí, con la cookie | `https://<host de inicio de sesión>`. |
| `If-Match` | no | Una versión, `"<versión>"`, de la lista de miembros. Una versión que no coincide, o más de una versión, devuelve `412 precondition_failed`. |

`org_id`: el identificador de la organización (`org_…`). `membership_id`: el identificador de la membresía (`mem_…`).

Cuerpo: `{"role_ids": ["rol_…"]}`, con un máximo de 50 roles. `role_ids` es obligatorio; `[]` es un conjunto válido.

## Respuesta

`200 OK` con la membresía (los mismos campos que un elemento de [la lista de miembros](/docs/api/fapi/organizations/memberships/list)) y `ETag: "<versión>"`.

## Errores

| Estado | Código | Cuándo |
| --- | --- | --- |
| 400 | `malformed_request` | `If-Match` está mal formado. |
| 400 | `unknown_field` | El cuerpo tiene un campo distinto de `role_ids`. |
| 401 | `unauthenticated` | No hay cookie de sesión ni token válidos. |
| 403 | `insufficient_permissions` | El usuario no tiene `idp_members:update_roles` en la organización. |
| 403 | `role_not_assignable` | Una regla de asignación anterior rechaza el cambio. |
| 403 | `origin_not_allowed` | El `Origin` no coincide. |
| 404 | `not_found` | No existe la organización, la membresía o el rol para este usuario; un identificador desconocido, mal formado o ajeno recibe la misma respuesta. |
| 409 | `last_org_admin` | El cambio dejaría la organización sin un administrador activo. |
| 409 | `role_limit_reached` | El miembro tendría más de 50 roles. |
| 409 | `organization_disabled` | La organización está deshabilitada o pendiente de eliminación (`organization_pending_deletion`). |
| 412 | `precondition_failed` | `If-Match` no indica la versión actual de la membresía. |
| 422 | `validation_failed` | Falta `role_ids`, es demasiado largo o contiene un identificador mal formado. |
| 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/memberships/mem_01jbz6x8kq3m2n4p5r6s7t8v9b/roles" \
  -H "Idp-Client: my-app/1.0.0 (node/22.0.0)" \
  -H "Origin: https://example.keenauth.app" \
  -H "Content-Type: application/json" \
  -H 'If-Match: "3"' \
  -b cookies.txt \
  -d '{"role_ids":["rol_01jbz6x8kq3m2n4p5r6s7t8v9w"]}'
```

```json
{
  "id": "mem_01jbz6x8kq3m2n4p5r6s7t8v9b",
  "user_id": "usr_01jbz6x8kq3m2n4p5r6s7t8v9c",
  "status": "active",
  "roles": [{ "role_id": "rol_01jbz6x8kq3m2n4p5r6s7t8v9w", "source": "admin_api" }],
  "created_at": "2026-11-03T09:00:00Z",
  "activated_at": "2026-11-03T09:00:00Z",
  "expires_at": null,
  "updated_at": "2026-11-03T10:00:00Z",
  "version": 4
}
```

## Datos personales

Este endpoint contiene datos personales: membresías de organizaciones e invitaciones. [Datos personales en las API de KeenAuth](/docs/policies/personal-data) describe qué se almacena, durante cuánto tiempo se conserva y cómo se elimina. No envíe categorías especiales de datos personales (salud, datos biométricos, religión, opiniones políticas, orientación sexual) en ningún campo.