Riferimento controllo accessi

Capgo utilizza controllo degli accessi basato sui ruoli (RBAC) per gestire le autorizzazioni di ogni membro del team. I ruoli sono organizzati per ambito — dall'intera organizzazione fino al singolo bundle.

Per una guida visiva sulla gestione dei membri nel dashboard, consulta Organizzazione.

---

Scope dei ruoli

Ogni ruolo appartiene a uno scope che determina a quali risorse garantisce l'accesso.

Ambito	Si applica a	Esempio di utilizzo
Organizzazione	L'intera org e tutte le sue app	Il tuo co-founder riceve Super Admin; il tuo commercialista riceve Billing Manager
App	Una singola app e i suoi canali	Un contractor su un'app riceve il ruolo App Developer
Canale	Un singolo canale all'interno di un'app	Un QA engineer gestisce solo il staging canale
Bundle	Una singola versione del bundle	Un reviewer ha accesso in sola lettura a un rilascio specifico

Un membro può avere un ruolo per ogni ambito — ad esempio, un ruolo org, un ruolo sull'App A e un ruolo diverso sull'App B.

---

Ruoli dell'organizzazione

Questi ruoli vengono assegnati durante l'invito di un membro. Garantiscono l'accesso a tutta l'organizzazione.

Ruolo	Nome interno	Descrizione
Super Admin	org_super_admin	Equivalente all'Owner. Controllo totale, inclusa l'eliminazione dell'org, la gestione del billing e il trasferimento delle app. Assegnato automaticamente al creatore dell'org.
Admin	org_admin	Amministrazione completa — gestione di membri, app e channel. Non può eliminare l'org, aggiornare il billing, trasferire app o promuovere utenti a Super Admin.
Responsabile della fatturazione	org_billing_admin	Accesso solo fatturazione: visualizza e aggiorna informazioni di fatturazione, fatture e log di audit. Nessun accesso ad app o membri.
Membro	org_member	Accesso in sola lettura all'org e a tutte le sue app.

Matrice dei permessi dell'organizzazione

Permesso	Descrizione	Super Admin	Admin	Responsabile della fatturazione	Membro
org.read	Visualizza l'organizzazione	✅	✅	✅	✅
org.update_settings	Modifica nome org, logo, email di gestione	✅	✅	❌	❌
org.delete	Elimina definitivamente l'organizzazione	✅	❌	❌	❌
org.read_members	Visualizza la lista dei membri	✅	✅	❌	✅
org.invite_user	Invita nuovi membri	✅	✅	❌	❌
org.update_user_roles	Cambia i ruoli dei membri (l'Admin non può promuovere a Super Admin — bloccato dalla gerarchia)	✅	✅	❌	❌
org.read_billing	Visualizza info di fatturazione e piano attuale	✅	✅	✅	❌
org.update_billing	Aggiorna metodo di pagamento e piano	✅	❌	✅	❌
org.read_invoices	Visualizza le fatture	✅	✅	✅	❌
org.read_audit	Visualizza il log di attività dell'organizzazione	✅	✅	❌	❌
org.read_billing_audit	Visualizza il log di audit della fatturazione	✅	✅	✅	❌

Nota

I ruoli dell'organizzazione ereditano tutti i permessi dei ruoli di app, channel e bundle sottostanti nella gerarchia. Un Super Admin può fare tutto ciò che fa un Admin App o Amministratore del canale può operare su tutte le app e i canali.

---

Ruoli dell'app

Limitati a una singola app. Usali quando un membro del team deve lavorare su una sola app e non sull'intera organizzazione.

Ruolo	Nome interno	Descrizione
Admin App	app_admin	Controllo totale di un'app: canali, dispositivi e ruoli utente dell'app. Non può eliminare o trasferire l'app (operazioni a livello di org).
Sviluppatore App	app_developer	Upload di bundle, gestione dispositivi, trigger di native build e aggiornamento impostazioni canali. Nessuna eliminazione, modifica impostazioni app o creazione canali.
App Uploader	app_uploader	Accesso in lettura + upload di nuove versioni del bundle.
App Reader	app_reader	Sola lettura — statistiche, bundle, canali, log, dispositivi.
Anteprima App	app_preview	Ciclo di vita CI per anteprime legate all'organizzazione e all'app: carica un bundle e crea un canale di anteprima. La creazione del canale concede automaticamente i diritti di lifecycle solo per quello.

Matrice dei permessi dell'app

Permesso	Descrizione	Admin App	Sviluppatore App	App Uploader	App Reader
app.read	Visualizza dettagli, statistiche e metadati dell'app	✅	✅	✅	✅
app.update_settings	Modifica le impostazioni dell'app	✅	❌	❌	❌
app.read_bundles	Visualizza l'elenco dei bundle caricati	✅	✅	✅	✅
app.upload_bundle	Carica una nuova versione del bundle	✅	✅	✅	❌
app.create_channel	Crea un nuovo canale	✅	❌	❌	❌
app.read_channels	Visualizza i canali	✅	✅	✅	✅
app.read_logs	Visualizza i log di consegna degli aggiornamenti	✅	✅	✅	✅
app.manage_devices	Assegna, sovrascrivi o scollega i dispositivi	✅	✅	❌	❌
app.read_devices	Visualizza l'elenco dei dispositivi	✅	✅	✅	✅
app.build_native	Avvia una native cloud build	✅	✅	❌	❌
app.read_audit	Visualizza i log di attività dell'app	✅	✅	✅	✅
app.update_user_roles	Gestisci l'assegnazione dei ruoli per singola app	✅	❌	❌	❌
bundle.delete	Elimina un bundle	✅	❌	❌	❌

Nota

app.delete e app.transfer sono operazioni a livello di organizzazione — solo org_super_admin può eseguirle, indipendentemente dai ruoli a livello di app.

Set di permessi App Preview

Usa Anteprima App (app_preview) per una chiave CI legata all'organizzazione e all'app che gestisce il ciclo di vita delle preview delle PR senza accessi estesi all'app o all'organizzazione.

Il app_preview il binding concede solo questi permessi a livello di app:

Permesso	Consente
app.read	Leggere l'app selezionata
app.read_bundles	Leggi i bundle caricati
app.upload_bundle	Carica un bundle
app.create_channel	Crea un canale

Quando una App Preview key crea un canale, Capgo assegna automaticamente a quella key un binding channel_preview figlio solo per il nuovo canale:

Permesso	Consente di
channel.read	Leggere il canale creato dalla key
channel.promote_bundle	Impostare il bundle caricato dalla key su quel canale
channel.delete	Eliminare quel canale

Perché app_preview mantiene app.read, la chiave può elencare i metadati del canale nell'app selezionata. Il binding automatico dei figli è un limite di gestione: non concede mutazioni del ciclo di vita per un canale che la chiave non ha creato.

Capgo registra la preview key che ha creato ogni canale e caricato ogni bundle. Pertanto, una App Preview key può creare ogni canale preview non pubblico necessario, promuovere il proprio bundle e cancellare atomicamente quel canale e bundle con channel delete --delete-bundle; non può eseguire queste operazioni su un canale default/main esistente, sul canale di un'altra preview key o sul bundle di un'altra chiave.

It does not include app.update_settingsla gestione di device o ruoli, channel.update_settings, channel.rollback_bundlela gestione dei device forzati o bundle.delete.

Attenzione

Ogni binding App Preview rimane collegato all'organizzazione proprietaria dell'app selezionata. Il ruolo non è un ruolo a livello di organizzazione; non rimuove l'associazione con l'organizzazione. Revocare o far scadere il binding dell'app rimuove l'accesso effettivo al ciclo di vita della chiave.

---

Ruoli del canale

Limitati a un singolo canale. Utili per concedere accessi mirati a un canale di rilascio specifico.

Nota

I ruoli del canale sono attualmente disponibili solo tramite API e CLI — non esiste un'interfaccia nel dashboard per assegnarli. channel_preview è un'eccezione: Capgo la crea automaticamente per una chiave App Preview quando tale chiave crea un canale. Nella dashboard, usa override dei permessi per canale invece per gestire i permessi del canale per singolo utente.

Ruolo	Nome interno	Descrizione
Admin del canale	channel_admin	Controllo totale di un canale: impostazioni, promozione/rollback bundle e gestione dispositivi forzati.
Viewer del canale	channel_reader	Sola lettura — bundle attuale, cronologia, dispositivi forzati e audit log.
Preview del canale	channel_preview	Assegnato al tasto App Preview che ha creato il canale: può leggere, promuovere il proprio bundle e cancellare il canale.

Matrice dei permessi del canale

Permesso	Descrizione	Admin del canale	Visualizzatore canale	Anteprima canale
channel.read	Visualizza il canale e il bundle attuale	✅	✅	✅
channel.update_settings	Modifica le impostazioni del canale (toggle piattaforma, policy di aggiornamento...)	✅	❌	❌
channel.delete	Elimina il canale	✅	❌	✅
channel.read_history	Visualizza la cronologia delle assegnazioni dei bundle	✅	✅	❌
channel.promote_bundle	Imposta il bundle attivo sul canale	✅	❌	✅
channel.rollback_bundle	Effettua il rollback a un bundle precedente	✅	❌	❌
channel.manage_forced_devices	Forza dispositivi specifici su questo canale	✅	❌	❌
channel.read_forced_devices	Visualizza l'elenco dei dispositivi forzati	✅	✅	❌
channel.read_audit	Visualizza i log di attività del canale	✅	✅	❌

---

Ruoli del bundle

Limitato a una singola versione del bundle. Raramente necessario — la maggior parte dei team usa ruoli a livello di app.

Nota

I ruoli del bundle sono attualmente disponibili solo tramite API e CLI — non esiste un'interfaccia nel dashboard per assegnarli.

Ruolo	Nome interno	Descrizione
Amministratore Bundle	bundle_admin	Leggi, aggiorna i metadati e cancella un bundle specifico.
Visualizzatore bundle	bundle_reader	Accesso in sola lettura a un bundle specifico.

---

Override permessi canale (Dashboard)

Nella dashboard, l'accesso ai canali è determinato per impostazione predefinita dal ruolo dell'utente nell'app. Per un controllo più granulare, puoi sovrascrivere i permessi di canali specifici per utente o gruppo senza cambiarne il ruolo nell'app.

Gli override si configurano dalla scheda Accesso dell'app cliccando sul pulsante permessi canale (icona scudo) accanto a un utente. Vedi Organizzazione — Override dei permessi dei canali per una guida visiva.

Permessi sovrascrivibili

Permesso	Descrizione	Comportamento predefinito
Lettura	Visualizza il canale e il bundle attuale	Ereditato dal ruolo dell'app
Cronologia	View the bundle assignment history	Ereditato dal ruolo dell'app
Associa bundle	Imposta o cambia il bundle attivo sul canale	Ereditato dal ruolo dell'app

Ogni permesso può essere impostato su:

• Predefinito — eredita dal ruolo dell'app (default)
• Consenti — concedi esplicitamente, indipendentemente dal ruolo dell'app
• Nega — blocca esplicitamente, indipendentemente dal ruolo dell'app

Questo ti permette, ad esempio, di dare a un App Reader la possibilità di associare bundle sul staging canale senza promuoverlo ad App Developer.

---

Gerarchia dei ruoli

I ruoli formano una gerarchia. Un ruolo genitore eredita tutti i permessi dei suoi ruoli figli. Ciò significa che un org_admin può fare tutto ciò che fa un app_admin può, che a sua volta può fare tutto ciò che un channel_admin può fare, e così via.

Super Admin (org_super_admin)
  └── Admin (org_admin)
        └── App Admin (app_admin)
              ├── App Developer (app_developer)
              │     └── App Uploader (app_uploader)
              │           └── App Reader (app_reader)
              ├── Bundle Admin (bundle_admin)
              │     └── Bundle Viewer (bundle_reader)
              └── Channel Admin (channel_admin)
                    └── Channel Viewer (channel_reader)

Come funziona in pratica:

• Un Admin a livello di org può fare tutto ciò che può fare un Admin App può, su ogni app dell'org.
• Un Admin App su un'app specifica può fare tutto ciò che un Amministratore del canale può, su ogni channel di quell'app.
• Un Sviluppatore App può fare tutto ciò che fa un App Uploader può, e molto altro ancora.

La gerarchia fluisce solo verso il basso — un channel_admin non ottiene mai permessi a livello di organizzazione, anche se possiede un ruolo a livello di app.

---

Gruppi

Invece di assegnare i ruoli a ogni singolo utente, puoi creare dei gruppi e assegnare i ruoli al gruppo. Ogni membro del gruppo eredita automaticamente tali ruoli.

Come funzionano i gruppi

• Un gruppo appartiene a una sola organizzazione — non può estendersi su più org.
• I gruppi possono contenere role binding a qualsiasi scope: org, app, channel o bundle. Ad esempio, un gruppo può avere il Sviluppatore App role sull'App A e il Amministratore del canale role sul staging channel dell'App B.
• Quando vengono valutati i permessi di un utente, tutte le sue appartenenze ai gruppi vengono risolte in modo trasparente. Se uno qualsiasi dei suoi gruppi concede il permesso richiesto, l'accesso è consentito.
• Un utente può appartenere a gruppi multipli, e i permessi di tutti i gruppi si sommano.
• I permessi basati su gruppo si applicano solo a principal utente — le chiavi API non ereditano i ruoli del gruppo.

Quando usare i gruppi

Scenario	Senza gruppi	Con i gruppi
5 ingegneri QA devono avere accesso Developer a 3 app	15 binding di ruolo individuali	1 gruppo + 3 role binding
Qualcuno entra nel team QA	Aggiungi 3 role binding manualmente	Aggiungili al gruppo
Qualcuno lascia il team QA	Rimuovi 3 role binding manualmente	Rimuovili dal gruppo

Gestione dei gruppi tramite API

Tutti gli endpoint dei gruppi richiedono autenticazione e sono serviti sotto /private/groups.

Elenca i gruppi

curl -X GET "https://api.capgo.app/private/groups/<ORG_ID>" \
  -H "authorization: <API_KEY>"

Richiede org.read_members permessi.

Crea un gruppo

curl -X POST "https://api.capgo.app/private/groups/<ORG_ID>" \
  -H "authorization: <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "QA Team",
    "description": "Quality assurance engineers"
  }'

Richiede org.update_user_roles permessi (Super Admin o Admin).

Aggiorna un gruppo

curl -X PUT "https://api.capgo.app/private/groups/<GROUP_ID>" \
  -H "authorization: <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "QA Team",
    "description": "Updated description"
  }'

Elimina un gruppo

curl -X DELETE "https://api.capgo.app/private/groups/<GROUP_ID>" \
  -H "authorization: <API_KEY>"

L'eliminazione di un gruppo rimuove anche tutti i relativi role binding. I membri non vengono eliminati dall'organizzazione.

Elenca i membri del gruppo

curl -X GET "https://api.capgo.app/private/groups/<GROUP_ID>/members" \
  -H "authorization: <API_KEY>"

Aggiungi un membro a un gruppo

curl -X POST "https://api.capgo.app/private/groups/<GROUP_ID>/members" \
  -H "authorization: <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{ "user_id": "<USER_UUID>" }'

L'utente deve già far parte dell'organizzazione. Aggiungere un membro già presente non produce alcun effetto.

Rimuovi un membro da un gruppo

curl -X DELETE "https://api.capgo.app/private/groups/<GROUP_ID>/members/<USER_UUID>" \
  -H "authorization: <API_KEY>"

Nota

Per assegnare un ruolo a un gruppo, usa i role bindings API con principal_type: "group" e principal_id impostati sul UUID del gruppo.

---

Assegnazione dei ruoli tramite API

Elenca i membri

curl -X GET "https://api.capgo.app/organization/members" \
  -H "authorization: <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{ "orgId": "<ORG_ID>" }'

Risposta:

[
  {
    "uid": "user-uuid",
    "email": "alice@example.com",
    "image_url": "https://...",
    "role": "org_admin",
    "is_tmp": false
  }
]

Invita un membro

curl -X POST "https://api.capgo.app/organization/members" \
  -H "authorization: <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "orgId": "<ORG_ID>",
    "email": "bob@example.com",
    "invite_type": "org_admin"
  }'

Valori accettati per invite_type:

Valore	Ruolo assegnato
org_super_admin	Super Admin
org_admin	Admin
org_billing_admin	Responsabile della fatturazione
org_member	Membro

Rimuovi un membro

curl -X DELETE "https://api.capgo.app/organization/members" \
  -H "authorization: <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "orgId": "<ORG_ID>",
    "email": "bob@example.com"
  }'

---

Assegnazione dei ruoli tramite CLI

Elenca le organizzazioni

npx @capgo/cli organization list --apikey <API_KEY>

Elenca i membri

npx @capgo/cli organization members <ORG_ID> --apikey <API_KEY>

Nota

Attualmente CLI supporta solo l'elenco dei membri. Per invitare nuovi membri o modificare i ruoli programmaticamente, utilizza gli endpoint API indicati sopra.

---

Ruoli personalizzati

I ruoli predefiniti coprono la maggior parte delle strutture di team. La creazione di ruoli personalizzati è nella nostra roadmap — se è una funzione di cui il tuo team ha bisogno, reach out to us. Il tuo caso d'uso ci aiuterà a dare priorità a questa feature.

Continua dalla guida Access Control Reference

Se stai usando Riferimento controllo accessi per pianificare le operazioni della dashboard e di API, collegalo a Panoramica API per i dettagli di implementazione in Panoramica di API, Introduzione per i dettagli di implementazione in Introduzione, Chiavi API per i dettagli di implementazione delle chiavi API, Dispositivi per i dettagli di implementazione in Devices, e Bundle per il dettaglio di implementazione in Bundles.