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

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