# Imposta le autorizzazioni del ruolo

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

Sostituisce l'insieme di autorizzazioni di un ruolo dell'organizzazione. Possono essere usate solo le autorizzazioni che l'ambiente consente per i ruoli dell'organizzazione, e gli amministratori possono concedere solo le autorizzazioni che possiedono a loro volta. Qui non è possibile creare autorizzazioni né API. Richiede il cookie `__Host-idp_session` dell'utente autenticato; se il cookie manca, è scaduto o è stato revocato, restituisce `401 unauthenticated`. Un'app first-party su un'altra origine può invece inviare il proprio token di accesso alla Front API (`Authorization: DPoP <token>` con una prova DPoP; vedi [Token di accesso alla Front API](/docs/api/fapi/front-api-token)). L'utente deve essere un membro attivo dell'organizzazione con l'autorizzazione `idp_roles:manage`. Un utente che non è membro riceve `404 not_found`, così l'esistenza dell'organizzazione non viene rivelata; un membro senza l'autorizzazione riceve `403 insufficient_permissions`. I ruoli dell'organizzazione devono essere abilitati per l'ambiente e inclusi nel suo piano.

## Richiesta

Intestazioni:

| Intestazione | Obbligatoria | Descrizione |
| --- | --- | --- |
| `Idp-Client` | sì | Identificatore dell'SDK. |
| `Origin` | sì | Deve essere esattamente `https://<host di accesso>`. |
| `Content-Type` | con un body | `application/json`. |
| `If-Match` | no | `"<version>"` del ruolo come letto l'ultima volta; se il ruolo è cambiato nel frattempo, restituisce `412 precondition_failed` e nulla cambia. |

`org_id`: l'identificatore dell'organizzazione (`org_…`). `role_id`: l'identificatore del ruolo (`rol_…`).

Body:

| Campo | Obbligatorio | Descrizione |
| --- | --- | --- |
| `permission_ids` | sì | L'insieme completo, al massimo 100 identificatori di autorizzazione (`perm_…`); `[]` rimuove tutte. |

## Risposta

`200 OK` con un nuovo `ETag`; il body è il ruolo (vedi [Ottieni un ruolo dell'organizzazione](./get)).

## Errori

| Stato | Codice | Quando |
| --- | --- | --- |
| 401 | `unauthenticated` | Nessun cookie di sessione valido. |
| 403 | `origin_not_allowed` | `Origin` manca o è errato. |
| 403 | `insufficient_permissions` | L'utente non ha `idp_roles:manage` nell'organizzazione. |
| 403 | `plan_feature_unavailable` | Il piano dell'ambiente non include i ruoli dell'organizzazione (`feature`, `required_plan`). |
| 403 | `org_custom_roles_disabled` | I ruoli dell'organizzazione sono disattivati per l'ambiente. |
| 403 | `role_not_assignable` | Il ruolo, o il nuovo insieme, concede un'autorizzazione che l'utente non possiede, oppure l'appartenenza dell'utente stesso include il ruolo. |
| 404 | `not_found` | Nessuna organizzazione o ruolo dell'organizzazione per questo utente; un ruolo dell'ambiente, un identificatore sconosciuto, malformato o di un altro utente ottiene la stessa risposta. |
| 409 | `organization_pending_deletion` | L'organizzazione è programmata per l'eliminazione. |
| 412 | `precondition_failed` | `If-Match` non indica la versione corrente, oppure il ruolo è cambiato durante l'elaborazione della richiesta. |
| 422 | `permission_not_allowed` | Un'autorizzazione non è consentita per i ruoli dell'organizzazione. |
| 422 | `permission_reserved` | Un'autorizzazione è riservata alla piattaforma. |
| 422 | `validation_failed` | L'elenco non è valido o è troppo lungo. |
| 503 | `service_unavailable` | Temporaneamente non disponibile; riprova dopo `Retry-After`. |

## Esempio

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