Elenca i ruoli dell'organizzazione

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

Restituisce i ruoli propri dell'organizzazione e i ruoli dell'ambiente che gli amministratori dell'organizzazione possono assegnare, ordinati per identificatore. 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_…).

Parametri di query:

Parametro	Obbligatorio	Descrizione
`limit`	no	Dimensione della pagina, da 1 a 100; predefinito 20.
`after`	no	Il valore `next_after` della pagina precedente.

Nessun body.

Risposta

200 OK:

Campo	Tipo	Descrizione
`data[]`	object[]	Ruoli, con i campi descritti in Ottieni un ruolo dell'organizzazione.
`next_after`	string	Da passare come `after` per la pagina successiva; assente nell'ultima pagina.

{
  "data": [
    {
      "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
400	`invalid_cursor`	`after` non è un identificatore di ruolo proveniente da una pagina precedente.
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).
422	`validation_failed`	`limit` è fuori intervallo.
503	`service_unavailable`	Temporaneamente non disponibile; riprova dopo `Retry-After`.

Esempio

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