# Ottieni un ruolo dell'organizzazione

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

Restituisce un ruolo dell'organizzazione, oppure un ruolo dell'ambiente che gli amministratori dell'organizzazione possono assegnare. 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. |

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

Nessun body.

## Risposta

`200 OK` con un'intestazione `ETag` (`"<version>"`):

| Campo | Tipo | Descrizione |
| --- | --- | --- |
| `id` | string | Identificatore del ruolo (`rol_…`). |
| `organization_id` | string o null | Identificatore dell'organizzazione (`org_…`); `null` per un ruolo dell'ambiente offerto per l'assegnazione nell'organizzazione (qui sola lettura). |
| `key` | string | Chiave del ruolo; unica nell'organizzazione e tra i ruoli dell'ambiente; non cambia mai. |
| `name` | string | Nome visualizzato. |
| `description` | string | Descrizione; vuota se non impostata. |
| `is_privileged` | boolean | Indica se il ruolo concede autorizzazioni amministrative. |
| `assignable_in_self_service` | boolean | Indica se gli amministratori dell'organizzazione possono assegnare il ruolo. |
| `permission_ids` | string[] | Identificatori delle autorizzazioni (`perm_…`). |
| `created_at` | string | RFC 3339, UTC. |
| `updated_at` | string | RFC 3339, UTC. |
| `version` | integer | Versione corrente; inviata anche nell'intestazione `ETag` (`"<version>"`). |

```json
{
  "id": "rol_01jbz6x8kq3m2n4p5r6s7t8v9w",
  "organization_id": "org_01jbz6x8kq3m2n4p5r6s7t8v9a",
  "key": "auditor",
  "name": "Auditor",
  "description": "Read-only access to reports",
  "is_privileged": false,
  "assignable_in_self_service": true,
  "permission_ids": ["perm_01jbz6x8kq3m2n4p5r6s7t8v9b"],
  "created_at": "2026-10-28T09:30:00Z",
  "updated_at": "2026-10-28T09:30:00Z",
  "version": 1
}
```

## Errori

| Stato | Codice | Quando |
| --- | --- | --- |
| 401 | `unauthenticated` | Nessun cookie di sessione valido. |
| 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 per questo utente (un identificatore sconosciuto, malformato o di un altro utente ottiene la stessa risposta). |
| 503 | `service_unavailable` | Temporaneamente non disponibile; riprova dopo `Retry-After`. |

## Esempio

```bash
curl https://example.keenauth.app/fapi/v1/organizations/org_01jbz6x8kq3m2n4p5r6s7t8v9a/roles/rol_01jbz6x8kq3m2n4p5r6s7t8v9w \
  -H "Idp-Client: my-app/1.0.0 (node/22.0.0)" \
  -b cookies.txt
```