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). 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) 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

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"]}'

{
  "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 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).