Access Control Reference

Capgo utilizza il controllo degli accessi basato sul ruolo (RBAC) per gestire cosa può fare ogni membro del team. I ruoli sono organizzati per ambito – dall'intera organizzazione fino a un singolo pacchetto.

Per una panoramica visiva della gestione dei membri nel pannello di controllo, vedi Organizzazione.

---

Scopi di ruolo

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

Scope	Si applica a	Esempio di utilizzo
Organizzazione	L'intera organizzazione e tutti i suoi app	Tuoi co-fondatori ottengono Super Amministratore; il tuo contabile ottiene Gestore fatturazione
App	Una singola app e i suoi canali	Un contrattore che lavora su un'applicazione ottiene lo status di App Developer
Canale	Un singolo canale all'interno di un'applicazione	Un ingegnere QA gestisce solo il staging canale
Pacco	Una versione di pacchetto singola	Un revisore ha bisogno di accesso di sola lettura a una versione di rilascio specifica

Un membro può avere un ruolo per ambito di destinazione — ad esempio, un ruolo di organizzazione, un ruolo su App A e un ruolo diverso su App B.

---

Ruoli di organizzazione

Questi ruoli vengono assegnati quando si invita un membro. Concedono accesso all'intera organizzazione.

Ruolo	Nome interno	Descrizione
Super Amministratore	org_super_admin	Equivalente di proprietario. Controllo completo, inclusa la possibilità di cancellare l'org, gestire la fatturazione e trasferire le app. Concesso automaticamente al creatore dell'org.
Amministratore	org_admin	Amministrazione completa — gestire membri, app, canali. Non è possibile cancellare l'org, aggiornare la fatturazione, trasferire le app o promuovere gli utenti a Super Amministratore.
Responsabile della Fatturazione	org_billing_admin	Accesso solo alla fatturazione: visualizzare e aggiornare le informazioni sulla fatturazione, le fatture e i registri di audit della fatturazione. Nessun accesso alle app o ai membri.
Utente	org_member	Accesso di sola lettura all'org e a tutti i suoi app.

Matrice delle autorizzazioni dell'org

Autorizzazione	Descrizione	Amministratore Superiore	Amministratore	Responsabile Gestione Fatture	Membro
org.read	Visualizza l'org	✅	✅	✅	✅
org.update_settings	Modifica nome, logo, email di gestione dell'org	✅	✅	❌	❌
org.delete	Cancella permanentemente l'org	✅	❌	❌	❌
org.read_members	Visualizza la lista dei membri	✅	✅	❌	✅
org.invite_user	Invita nuovi membri	✅	✅	❌	❌
org.update_user_roles	Cambia i ruoli dei membri (l'amministratore non può promuovere a Super Amministratore — bloccato dalla gerarchia dei ruoli)	✅	✅	❌	❌
org.read_billing	Visualizza le informazioni di fatturazione e il piano attuale	✅	✅	✅	❌
org.update_billing	Aggiorna il metodo di pagamento e il piano	✅	❌	✅	❌
org.read_invoices	Visualizza le fatture	✅	✅	✅	❌
org.read_audit	Visualizza il registro di attività dell'organizzazione	✅	✅	❌	❌
org.read_billing_audit	Visualizza il registro di audit specifico per la fatturazione	✅	✅	✅	❌

Nota

Il ruolo dell'organizzazione eredita tutte le autorizzazioni dell'app, del canale e del bundle che si trovano sotto di esso nella gerarchia. A Super Amministratore può fare tutto ciò che un Amministratore dell'app o Amministratore del canale può fare, su tutti gli app e canali.

---

Ruoli dell'app

Limitato a un'app sola. Utilizzare questi quando un membro della squadra dovrebbe lavorare solo su un'app, non sull'intera organizzazione.

Ruolo	Nome interno	Descrizione
Amministratore dell'app	app_admin	Controllo totale di un'applicazione — canali, dispositivi, ruoli utente per l'applicazione. Non è possibile cancellare o trasferire l'app (queste sono operazioni a livello di organizzazione).
Applicazione sviluppatrice	app_developer	Carica bundle, gestisci dispositivi, attiva costruzioni native, aggiorna impostazioni dei canali. Nessuna cancellazione, nessuna modifica delle impostazioni dell'app, nessuna creazione di canali.
Caricatore di applicazioni	app_uploader	Accesso di sola lettura + caricamento di nuove versioni dei bundle.
Letture solo — statistiche, bundle, canali, log, dispositivi.	app_reader	Anteprima dell'applicazione
Ciclo di vita della preview dell'organizzazione e dell'applicazione: caricare un bundle e creare un canale di anteprima. La creazione di quel canale concede automaticamente i diritti di ciclo di vita solo per esso.	app_preview	Matrice dei permessi dell'applicazione

Sottosezione intitolata “Matrice dei permessi dell'applicazione”

App permission matrix	Descrizione	Amministratore dell'app	Developatore dell'app	Caricatore dell'app	Lettore dell'app
app.read	Visualizza dettagli, statistiche e metadati dell'app	✅	✅	✅	✅
app.update_settings	Modifica le impostazioni dell'app	✅	❌	❌	❌
app.read_bundles	Visualizza la lista dei bundle caricati	✅	✅	✅	✅
app.upload_bundle	Carica una nuova versione del bundle	✅	✅	✅	❌
app.create_channel	Creare un nuovo canale	✅	❌	❌	❌
app.read_channels	Visualizza i canali	✅	✅	✅	✅
app.read_logs	Visualizza i registri di consegna degli aggiornamenti	✅	✅	✅	✅
app.manage_devices	Assegna, sovrappone o disconnetti dispositivi	✅	✅	❌	❌
app.read_devices	Visualizza la lista dei dispositivi	✅	✅	✅	✅
app.build_native	Avvia una costruzione cloud nativa	✅	✅	❌	❌
app.read_audit	Visualizza il registro di attività a livello di app	✅	✅	✅	✅
app.update_user_roles	Gestisci assegnazioni di ruoli a livello di 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 dell'applicazione.

Impostazione di permessi di anteprima dell'applicazione

Usa Anteprima dell'applicazione (app_preview) per una chiave di CI legata all'organizzazione e all'applicazione che gestisce il ciclo di vita dell'anteprima di una PR senza accesso ampio all'applicazione o all'organizzazione.

Il app_preview la condivisione concede solo questi permessi dell'applicazione:

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

Quando una chiave App Preview crea un canale, Capgo dà automaticamente a quella chiave una chiave figlia channel_preview per il nuovo canale solo:

Autorizzazione	Consenti
channel.read	Leggi il canale creato dalla chiave
channel.promote_bundle	Imposta il bundle caricato dalla chiave su quel canale
channel.delete	Elimina quel canale

Poiché app_preview conserva app.readla chiave può enumerare i metadati del canale selezionato nell'app. L'assegnazione figlia automatica è un Gestione Limite: non concede mutazioni di ciclo di vita per un canale la chiave non ha creato.

Capgo registra la chiave di anteprima che ha creato ogni canale e caricato ogni bundle. Quindi una chiave di anteprima dell'applicazione può creare ogni canale di anteprima non pubblico che necessita, promuovere il proprio bundle e cancellare atomicamente quel canale e bundle con channel delete --delete-bundlenon include

gestione del dispositivo o del ruolo app.update_settingsgestione del dispositivo forzata o generica channel.update_settings, channel.rollback_bundleAttento bundle.delete.

Ogni legame di anteprima dell'applicazione rimane collegato all'organizzazione di proprietà dell'applicazione selezionata. Il ruolo omette un ruolo organizzativo; non elimina l'associazione dell'organizzazione. La revoca o la scadenza del legame dell'applicazione elimina l'accesso di ciclo di vita effettivo della chiave.

Ruoli dei canali

---

Sottosezione intitolata “Ruoli dei canali”

Riservato a un singolo canale. Utile per fornire accesso mirato a un canale di rilascio specifico.

Nota

I ruoli dei canali sono attualmente disponibili tramite API e CLI solo — non esiste una UI per assegnarli nel pannello di controllo. channel_preview è un'eccezione: Capgo lo crea automaticamente per una chiave di anteprima dell'app quando quella chiave crea un canale. Nel pannello di controllo, utilizza override delle autorizzazioni dei canali per regolare l'accesso al canale per utente.

Ruolo	Nome interno	Descrizione
Canale Amministratore	channel_admin	Controllo completo di un canale: impostazioni, promuovi/riporta bundle, gestisci dispositivi obbligatori.
Canale Visualizzatore	channel_reader	Solo lettura — bundle corrente, storia, dispositivi obbligatori, registro di audit.
Canale Anteprima	channel_preview	Assegnato automaticamente al chiave anteprima dell'applicazione che ha creato il canale: lettura, promuovi il proprio bundle e cancella quel canale.

Matrice di permessi del canale

Permesso	Descrizione	Amministratore del canale	Visualizzatore del canale	Anteprima del canale
channel.read	Visualizza il canale e il suo bundle corrente	✅	✅	✅
channel.update_settings	Modifica le impostazioni del canale (toggle di piattaforma, politica di aggiornamento…)	✅	❌	❌
channel.delete	Cancella il canale	✅	❌	✅
channel.read_history	Visualizza la cronologia delle assegnazioni del bundle	✅	✅	❌
channel.promote_bundle	Imposta il bundle attivo sul canale	✅	❌	✅
channel.rollback_bundle	Ripristina un bundle precedente	✅	❌	❌
channel.manage_forced_devices	Forza dispositivi specifici a questo canale	✅	❌	❌
channel.read_forced_devices	Visualizza l'elenco dei dispositivi forzati	✅	✅	❌
channel.read_audit	Visualizza il registro di attività del canale	✅	✅	❌

---

Ruoli del bundle

Riservato a una sola versione del pacchetto. Raramente necessario — la maggior parte delle squadre utilizza invece ruoli a livello di applicazione.

Nota

I ruoli del pacchetto sono attualmente disponibili via API e CLI solo — non esiste una UI per assegnarli nel dashboard.

Ruolo	Nome interno	Descrizione
Amministratore del pacchetto	bundle_admin	Leggi, aggiorna i metadati e cancella un pacchetto specifico.
Visualizzatore del pacchetto	bundle_reader	Accesso di sola lettura a una specifica raccolta.

---

Override delle autorizzazioni del canale (Dashboard)

Nell'area di controllo, l'accesso al canale è determinato dal ruolo dell'applicazione dell'utente di default. Per un controllo più dettagliato, puoi sovrascrivere le autorizzazioni del canale specifiche per utente o gruppo senza modificare il ruolo dell'applicazione.

Gli override sono configurati dalla scheda Accesso del tuo app, cliccando sul pulsante delle autorizzazioni del canale (icona scudo) accanto a un utente. Vedi Organizzazione — Override delle autorizzazioni del canale per una guida visiva.

Le autorizzazioni sovrascrivibili

Autorizzazione	Descrizione	Comportamento predefinito
Leggi	Visualizza il canale e il suo bundle corrente	Ereditato dal ruolo dell'applicazione
Storia	Visualizza la storia delle assegnazioni del bundle	Ereditato dal ruolo dell'applicazione
Associare bundle	Imposta o modifica il bundle attivo sul canale	Inerente dal ruolo dell'applicazione

Ogni autorizzazione può essere impostata su:

• Predefinito — ereditare dal ruolo dell'applicazione (il valore predefinito)
• Consenti — concedere esplicitamente, indipendentemente dal ruolo dell'applicazione
• Nega — bloccare esplicitamente, indipendentemente dal ruolo dell'applicazione

Questo ti consente, ad esempio, di dare a un lettore dell'applicazione la possibilità di associare pacchetti sul staging canale senza promuoverli a sviluppatore dell'applicazione.

---

Gerarchia dei ruoli

I ruoli formano una gerarchia. Un ruolo padre eredita tutti i permessi dei suoi figli. Ciò significa che un org_admin può fare tutto ciò che può fare un app_admin che in turn può fare tutto ciò che può fare un channel_admin che può fare tutto ciò che può fare un

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)

può fare tutto ciò che può fare un

• può fare tutto ciò che può fare un può fare tutto ciò che può fare un può fare tutto ciò che può fare un può fare tutto ciò che può fare un App Admin può, su ogni app nell'org.
• Un Amministratore dell'app su un'app specifica può fare tutto ciò che può fare un Amministratore del canale , su ogni canale in quell'app.
• Un Sviluppatore dell'app può fare tutto ciò che può fare un Caricatore dell'app , più ancora.

La gerarchia fluisce solo in questo modo. in discesa — un channel_admin mai guadagna permessi di livello organizzativo, anche se detiene anche un ruolo di livello applicativo.

---

Gruppi

Invece di assegnare ruoli a ogni utente individualmente, puoi creare gruppi e assegnare ruoli al gruppo. Ogni membro del gruppo eredita automaticamente quei ruoli.

Come funzionano i gruppi

• Un gruppo appartiene a un'organizzazione Non può coprire più organizzazioni.
• I gruppi possono contenere vincoli di ruolo a qualsiasi ambito: organizzazione, app, canale o pacchetto. Ad esempio, un gruppo può essere assegnato al Ruolo sviluppatore dell'app su App A e al Ruolo amministratore del canale su il canale di App B. staging Quando vengono valutate le autorizzazioni di un utente, tutte le sue appartenenze ai gruppi vengono risolte in modo trasparente. Se uno dei suoi gruppi concede la autorizzazione richiesta, l'accesso è consentito.
• Un utente può appartenere a
• gruppi multiplo __CAPGO_KEEP_0__e le autorizzazioni dei permessi di tutti i gruppi sono additive.
• Il permessi dei gruppi si applicano solo ai principali degli utenti — le chiavi API non ereditano i ruoli dei gruppi.

Quando utilizzare i gruppi

Caso di studio	Senza gruppi	Con gruppi
5 ingegneri QA hanno bisogno di accesso allo sviluppatore per 3 app	15 vincoli di ruolo individuali	1 gruppo + 3 vincoli di ruolo
Qualcuno entra a far parte del team di QA	Aggiungi 3 vincoli di ruolo manualmente	Aggiungili al gruppo
Qualcuno lascia il team di QA	Rimuovi 3 vincoli di ruolo manualmente	Rimuovili dal gruppo

Gestione dei gruppi via API

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

Elenco dei gruppi

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

Richiede org.read_members la

permesso.

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"
  }'

Copia nel portapenne org.update_user_roles Richiedeil permesso ( Super Amministratore o il permesso di Amministratore).

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 elimina anche tutte le relative associazioni di ruolo. Gli utenti non vengono eliminati dall'organizzazione.

Elenco 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à essere un membro dell'organizzazione. Aggiungere un membro esistente è un'operazione senza effetti.

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, utilizzare i vincoli di ruolo API con principal_type: "group" e principal_id impostati sulla UUID del gruppo.

---

L'assegnazione dei ruoli tramite API

Elenco 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 Amministratore
org_admin	Amministratore
org_billing_admin	Gestore 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 di ruoli tramite CLI

Elenco delle organizzazioni

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

Elenco dei membri

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

Nota

Il CLI attualmente supporta l'elenco dei membri. Per invitare membri o modificare i ruoli in modo programmatico, utilizzare gli endpoint API sopra riportati.

---

Ruoli personalizzati

I ruoli predefiniti coprono la maggior parte delle strutture di squadra. La creazione di ruoli personalizzati è nel nostro piano di lavoro — se questo è qualcosa che il tuo team necessita, contattaci. Il tuo caso d'uso aiuterà direttamente a priorizzare questa funzionalità.

Continua da Access Control Reference

Se stai utilizzando Access Control Reference per pianificare il dashboard e le API operazioni, connettilo con API Overview per i dettagli di implementazione in API Overview, Introduzione per i dettagli di implementazione in Introduzione, API Chiavi per i dettagli di implementazione in API Chiavi, Dispositivi per i dettagli di implementazione in Dispositivi, e Bundle per i dettagli di implementazione in Bundle.