# Crea un ruolo dell'organizzazione

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

Crea un ruolo nell'organizzazione, senza autorizzazioni; aggiungile con [Imposta le autorizzazioni del ruolo](./set-permissions). Un'organizzazione può avere al massimo 50 ruoli. Richiede il cookie `__Host-idp_session` dell'utente autenticato; se il cookie manca, è scaduto o è stato revocato, restituisce `401 unauthenticated`. Un'applicazione first-party su un altro origin 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

Header:

| Header | Obbligatorio | Descrizione |
| --- | --- | --- |
| `Idp-Client` | sì | Identificatore dell'SDK. |
| `Origin` | sì | Deve essere esattamente `https://<host di accesso>`. |
| `Content-Type` | sì | `application/json`. |

`org_id`: l'identificatore dell'organizzazione (`org_…`).

Corpo:

| Campo | Obbligatorio | Descrizione |
| --- | --- | --- |
| `key` | sì | Chiave del ruolo; unica nell'organizzazione e tra i ruoli dell'ambiente; non può essere modificata in seguito. |
| `name` | sì | Nome visualizzato. |
| `description` | no | Descrizione. |

## Risposta

`201 Created` con gli header `Location` e `ETag`; il corpo è 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. |
| 404 | `not_found` | Nessuna organizzazione o ruolo di questo utente (un identificatore sconosciuto, non valido o non suo ottiene la stessa risposta). |
| 409 | `role_key_conflict` | La chiave è già usata nell'organizzazione o da un ruolo dell'ambiente. |
| 409 | `role_limit_reached` | L'organizzazione ha già 50 ruoli. |
| 409 | `organization_pending_deletion` | L'organizzazione è programmata per l'eliminazione. |
| 422 | `validation_failed` | Un campo manca o non è valido; `errors[]` lo indica. |
| 503 | `service_unavailable` | Temporaneamente non disponibile; riprova dopo `Retry-After`. |

## Esempio

```bash
curl -X POST https://example.keenauth.app/fapi/v1/organizations/org_01jbz6x8kq3m2n4p5r6s7t8v9a/roles \
  -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 '{"key":"auditor","name":"Auditor"}'
```