# Imposta i ruoli di un membro

`PUT /fapi/v1/organizations/{org_id}/memberships/{membership_id}/roles` · chiamato dall'host di accesso dell'ambiente

Sostituisce i ruoli di una membership con un insieme completo, per una schermata del profilo dell'organizzazione. L'insieme copre solo i ruoli che vedi in questa organizzazione: i suoi ruoli e i ruoli dell'ambiente aperti agli amministratori dell'organizzazione. Gli altri ruoli del membro restano. Un insieme vuoto rimuove tutti i ruoli che vedi; se al membro non ne resta nessuno, viene assegnato il ruolo predefinito dell'organizzazione.

Richiede il cookie `__Host-idp_session` dell'utente autenticato con un `Origin` esatto, oppure un access token dell'API front di un'app first-party (`Authorization: DPoP <token>` con una prova DPoP; vedi [Access token dell'API front](/docs/api/fapi/front-api-token)). L'utente deve essere un membro attivo dell'organizzazione con l'autorizzazione `idp_members:update_roles`. Un utente che non è membro riceve `404 not_found`; un membro senza l'autorizzazione riceve `403 insufficient_permissions`.

Regole di assegnazione:

- Ogni autorizzazione di ciascun ruolo che assegni deve essere una che tu possiedi a tua volta.
- Solo un membro che possiede il ruolo di amministratore può assegnare un ruolo privilegiato.
- Non puoi cambiare i tuoi ruoli.
- L'ultimo amministratore attivo non può perdere il ruolo di amministratore (`409 last_org_admin`).

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

## Richiesta

Intestazioni:

| Intestazione | Obbligatoria | Descrizione |
| --- | --- | --- |
| `Idp-Client` | sì | Identificatore dell'SDK. |
| `Origin` | sì, con il cookie | `https://<host di accesso>`. |
| `If-Match` | no | Una sola versione, `"<versione>"`, dall'elenco dei membri. Una versione che non corrisponde, o più di una versione, restituisce `412 precondition_failed`. |

`org_id`: l'identificatore dell'organizzazione (`org_…`). `membership_id`: l'identificatore della membership (`mem_…`).

Corpo: `{"role_ids": ["rol_…"]}`, al massimo 50 ruoli. `role_ids` è obbligatorio; `[]` è un insieme valido.

## Risposta

`200 OK` con la membership (gli stessi campi di un elemento di [l'elenco dei membri](/docs/api/fapi/organizations/memberships/list)) e `ETag: "<versione>"`.

## Errori

| Stato | Codice | Quando |
| --- | --- | --- |
| 400 | `malformed_request` | `If-Match` non è valida. |
| 400 | `unknown_field` | Il corpo contiene un campo diverso da `role_ids`. |
| 401 | `unauthenticated` | Nessun cookie di sessione o token valido. |
| 403 | `insufficient_permissions` | L'utente non ha `idp_members:update_roles` nell'organizzazione. |
| 403 | `role_not_assignable` | Una regola di assegnazione sopra blocca la modifica. |
| 403 | `origin_not_allowed` | L'`Origin` non corrisponde. |
| 404 | `not_found` | Nessuna organizzazione, membership o ruolo di questo tipo per questo utente; un identificatore inesistente, non valido o di un altro utente produce la stessa risposta. |
| 409 | `last_org_admin` | La modifica lascerebbe l'organizzazione senza un amministratore attivo. |
| 409 | `role_limit_reached` | Il membro avrebbe più di 50 ruoli. |
| 409 | `organization_disabled` | L'organizzazione è disattivata o in attesa di eliminazione (`organization_pending_deletion`). |
| 412 | `precondition_failed` | `If-Match` non corrisponde alla versione corrente della membership. |
| 422 | `validation_failed` | `role_ids` manca, è troppo lungo o contiene un identificatore non valido. |
| 503 | `service_unavailable` | Temporaneamente non disponibile; riprova dopo `Retry-After`. |

## Esempio

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

## Dati personali

Questo endpoint contiene dati personali: membership e inviti dell'organizzazione. [I dati personali nelle API di KeenAuth](/docs/policies/personal-data) descrive cosa viene memorizzato, per quanto tempo viene conservato e come viene eliminato. Non inviare in nessun campo categorie particolari di dati personali (salute, dati biometrici, religione, opinioni politiche, orientamento sessuale).