Riferimento al Controllo degli Accessi

Usa Capgo controllo di accesso basato sul ruolo (RBAC) per gestire cosa ogni membro del team può fare. I ruoli sono organizzati per ambito — dal'intera organizzazione fino a un singolo pacchetto.

Per una panoramica visiva sulla gestione dei membri nel pannello di controllo, vedere Organization.

---

Organizzazione

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

Scope	Ambito	Si applica a
Organizzazione	Tutta l'organizzazione e tutte le sue app	Il tuo co-fondatore ottiene Super Amministratore; il tuo contabile ottiene Gestore della fatturazione
App	Una singola app e i suoi canali	Un contrattista che lavora su una app ottiene Sviluppatore di app
Canale	Un canale singolo all'interno di un'app.	Un ingegnere di QA gestisce solo staging channel
Canale	Canale di distribuzione	A un revisore è necessario l'accesso di lettura a una versione specifica

Un membro può detenere 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 sono assegnati quando si invita un membro. Concedono l'accesso all'intera organizzazione.

Role	Nome interno	Nome interno
Descrizione	org_super_admin	Proprietario equivalente. Controllo completo, incluso la possibilità di eliminare l'organizzazione, gestire la fatturazione e trasferire le app. Concesso automaticamente al creatore dell'organizzazione.
Admin	org_admin	Amministrazione completa — gestisci membri, app, canali. Non puoi cancellare l'org, aggiornare la fatturazione, trasferire app o promuovere utenti a Super Amministratore.
Gestore fatturazione	org_billing_admin	Accesso solo per fatturazione: visualizza e aggiorna informazioni di fatturazione, fatture e registri di audit di fatturazione. Nessun accesso agli app o membri.
Membro	org_member	Accesso di sola lettura all'org e a tutte le sue app.

Matrice di autorizzazioni dell'org

Descrizione	Description	Super Admin	Admin	Amministratore fatturazione	Utente
org.read	Visualizza l'organizzazione	✅	✅	✅	✅
org.update_settings	Edit org name, logo, management email	✅	✅	❌	❌
org.delete	Cancella permanentemente l'organizzazione	✅	❌	❌	❌
org.read_members	Visualizza la lista degli utenti	✅	✅	❌	✅
org.invite_user	Invita nuovi membri	✅	✅	❌	❌
org.update_user_roles	Cambia ruoli degli utenti (l'amministratore non può promuovere a Super Amministratore — bloccato dalla gerarchia dei ruoli)	✅	✅	❌	❌
org.read_billing	View billing info and current plan	✅	✅	✅	❌
org.update_billing	Aggiorna metodo di pagamento e piano	✅	❌	✅	❌
org.read_invoices	Visualizza fatture	✅	✅	✅	❌
org.read_audit	Visualizza registro di attività dell'organizzazione	✅	✅	❌	❌
org.read_billing_audit	Visualizza registro di audit specifico per fatturazione	✅	✅	✅	❌

Nota

Il ruolo dell'organizzazione eredita tutte le autorizzazioni dell'app, del canale e del pacchetto di ruoli sottostanti nella gerarchia. Un Super Admin può fare tutto ciò che un App Admin o Amministratore del Canale possono fare, su tutti gli app e canali.

---

Ruoli dell'app

Limitato a un'applicazione. Utilizza questi quando un membro del team dovrebbe lavorare solo su un'applicazione, non sull'intera organizzazione.

Ruolo	Nome interno	Descrizione
App Admin	app_admin	Controllo completo di un'app — canali, dispositivi, ruoli utente per l'app. Non è possibile cancellare o trasferire l'app (queste operazioni sono a livello di organizzazione).
Sviluppatore dell'applicazione	app_developer	Carica bundle, gestisci dispositivi, attiva costruzioni native, aggiorna impostazioni del canale. Nessuna cancellazione, nessuna modifiche alle impostazioni dell'applicazione, nessuna creazione di canali.
Caricatore di bundle dell'applicazione	app_uploader	Read access + upload new bundle versions.
Letture App	app_reader	Letture esclusive — statistiche, bundle, canali, log, dispositivi.
Anteprima App	app_preview	Ciclo di vita della CI legato all'organizzazione e all'app: 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.

Matrice di permessi dell'app

Permesso	Descrizione	App Admin	Sviluppatore dell'app	Caricatore dell'app	Lettore dell'app
app.read	Visualizza dettagli dell'app, statistiche e metadati	✅	✅	✅	✅
app.update_settings	Modifica 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 registri di consegna degli aggiornamenti	✅	✅	✅	✅
app.manage_devices	Assegna, sovrapponi o disconnetti dispositivi	✅	✅	❌	❌
app.read_devices	Visualizza l'elenco dei dispositivi	✅	✅	✅	✅
app.build_native	Avvia un build cloud nativo	✅	✅	❌	❌
app.read_audit	Visualizza il registro di attività dell'app	✅	✅	✅	✅
app.update_user_roles	Gestisci le assegnazioni di ruoli dell'app	✅	❌	❌	❌
bundle.delete	Elimina un bundle	✅	❌	❌	❌

Nota

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

Set di autorizzazioni per anteprima di app

Usa Anteprima di app (app_previewPer una chiave CI associata all'organizzazione e all'applicazione che gestisce il ciclo di vita della preview di un PR senza accesso ampio per l'applicazione o l'organizzazione.

Questo app_preview concede solo questi permessi di livello di app:

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

Quando una chiave di anteprima dell'app crea un canale, Capgo assegna automaticamente a quella chiave un figlio channel_preview Leggi il canale creato dalla chiave

Permesso	Consente
channel.read	Leggi il canale creato dalla chiave
channel.promote_bundle	Imposta il proprio pacchetto caricato su quel canale
channel.delete	Cancella quel canale

Poiché app_preview conserva app.read, la chiave può enumerare i metadati del canale nella selezionata app. L'assegnazione automatica del figlio è un limite di gestione : non concede mutazioni di ciclo di vita per un canale che la chiave non ha creato.

Capgo registra la chiave di anteprima che ha creato ogni canale e caricato ogni pacchetto. Quindi una chiave di anteprima dell'applicazione può creare ogni canale di anteprima non pubblico che ha bisogno, promuovere il proprio pacchetto e cancellare atomicamente quel canale e pacchetto con channel delete --delete-bundlenon può farlo per un canale predefinito principale, un altro canale di anteprima chiave, o un altro bundle di chiave.

It does not include app.update_settings, la gestione dei dispositivi o dei ruoli channel.update_settings, channel.rollback_bundle, la gestione dei dispositivi forzata o generica bundle.delete.

Attenzione

Tutti i legami di anteprima dell'applicazione rimangono collegati all'applicazione selezionata dell'organizzazione proprietaria. Il ruolo omette un ruolo organizzativo; non elimina l'associazione dell'organizzazione. La revoca o la scadenza del legame dell'applicazione elimina l'accesso alla vita ciclo della chiave.

---

Ruoli di canale

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

Nota

I ruoli di canale sono attualmente disponibili attraverso API e CLI solo Non ci sono elementi UI per assegnarli nella dashboard. channel_preview è un'eccezione: Capgo lo crea automaticamente per una chiave di anteprima dell'applicazione quando quella chiave crea un canale. Nel pannello di controllo, utilizza override delle autorizzazioni del canale invece per regolare l'accesso al canale per utente.

Ruolo	Nome interno	Descrizione
Amministratore del canale	channel_admin	Controllo completo di un canale: impostazioni, promuovi/riporta bundle, gestisci dispositivi obbligatori.
Visualizzatore del canale	channel_reader	Letto solo — bundle corrente, storia, dispositivi obbligatori, registro degli accessi.
Anteprima del canale	channel_preview	Assegnato automaticamente alla chiave App Preview che ha creato il canale: lettura, promuovi il proprio bundle e cancella quel canale.

Matrice delle autorizzazioni 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	Edit channel settings (platform toggles, update policy…)	✅	❌	❌
channel.delete	Elimina il canale	✅	❌	✅
channel.read_history	Visualizza la cronologia delle assegnazioni del bundle	✅	✅	❌
channel.promote_bundle	Imposta il bundle attivo sul canale	✅	❌	✅
channel.rollback_bundle	Ritorna a un bundle precedente	✅	❌	❌
channel.manage_forced_devices	Imponi dispositivi specifici a questo canale	✅	❌	❌
channel.read_forced_devices	Visualizza l'elenco dei dispositivi obbligati	✅	✅	❌
channel.read_audit	Visualizza il registro delle attività del canale	✅	✅	❌

---

Gruppa i ruoli

Scoped to a single bundle version. Rarely needed — most teams use app-level roles instead.

Nota

I ruoli del pacchetto sono attualmente disponibili tramite API e CLI solo — non c'è un'interfaccia per assegnarli nel pannello di controllo.

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 un pacchetto specifico.

---

Autorizzazioni del canale sovrascritte (Dashboard)

Nel pannello 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.

Impostazioni di override sono configurate dall'app. Accesso Seleziona la scheda cliccando sul pulsante delle autorizzazioni del canale (icona scudo) accanto all'utente. Vedi Organizzazione — Sovrascrittura delle autorizzazioni del canale per una guida visiva.

Autorizzazioni sovrapponibili

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

Ogni autorizzazione può essere impostata su:

• Predefinito — ereditare dal ruolo dell'applicazione (predefinito)
• Consenti — assegna esplicitamente, indipendentemente dal ruolo dell'app
• Negare --- blocca esplicitamente, indipendentemente dal ruolo dell'app

Questo ti consente, ad esempio, di dare all'App Reader la possibilità di associare bundle sul staging canale senza promuoverli a sviluppatore di App.

---

Sottosezione intitolata “Gerarchia dei ruoli”

Ruoli formano una gerarchia. Un ruolo genitore eredita tutti i permessi può fare tutto ciò che può fare un org_admin può fare tutto ciò che un app_admin può, che inoltre può fare tutto ciò che un channel_admin Copia nel portapenne

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 nella pratica:

• Un Admin a livello di organizzazione può fare tutto ciò che un App Admin può fare, su ogni applicazione nell'organizzazione.
• Un App Admin su un'applicazione specifica può fare tutto ciò che un Amministratore del canale può fare, su ogni canale in quell'applicazione.
• Un Sviluppatore di App può fare tutto ciò che un Caricatore di App può fare, più cose.

La gerarchia si propaga solo in basso — un channel_admin ruolo non può mai ottenere permessi di livello organizzativo, neanche se detiene anche un ruolo di livello app.

---

Gruppi

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

Come funzionano i gruppi

• Un gruppo appartiene a una sola organizzazione – non può coprire più di un'org.
• I gruppi possono contenere vincoli di ruolo a qualsiasi ambito: org, app, canale o bundle. Ad esempio, un gruppo può essere assegnato il Ruolo sviluppatore di App ruolo su App A e il Ruolo amministratore del canale ruolo sul staging canale di App B.
• Quando vengono valutate le autorizzazioni di un utente, tutte le sue appartenenze ai gruppi vengono risolte in modo trasparente. Se qualsiasi gruppo concede la richiesta autorizzazione, l'accesso è consentito.
• Un utente può appartenere a gruppi multipli, e le autorizzazioni da tutti i gruppi sono additive.
• Istituzionali permessi sono applicabili solo ai principali utente — le chiavi API non ereditano ruoli di gruppo.

Quando utilizzare i gruppi

Scenario	Senza gruppi	Con gruppi
5 ingegneri QA richiedono accesso allo sviluppatore per 3 app	15 vincoli di ruolo individuali	1 gruppo + 3 vincoli di ruolo
Qualcuno entra a far parte del team QA	Aggiungere 3 vincoli di ruolo manualmente	Aggiungerli al gruppo
Qualcuno lascia il team QA	Rimuovere 3 vincoli di ruolo manualmente	Rimuoverli dal gruppo

Gestire i gruppi via API

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

Elenco gruppi

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

Richiede org.read_members la

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

Cancella un gruppo

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

La cancellazione di un gruppo elimina anche tutti i relativi vincoli di ruolo. I membri 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.

Sezione intitolata “Elenco membri del 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 impostare sul UUID del gruppo.

---

Assegnazione di 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 Admin
org_admin	Admin
org_billing_admin	Sezione intitolata “Assegna ruoli tramite __CAPGO_KEEP_0__”
org_member	Member

Sezione intitolata “Elenco organizzazioni”

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

---

Assegnare ruoli tramite CLI

Copia negli appunti

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

Elenco membri

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

Nota

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

---

Ruoli personalizzati

I ruoli predefiniti coprono la struttura di squadra più comune. La creazione di ruoli personalizzati è prevista per il nostro roadmap — se il tuo team ne ha bisogno, contattaci. Copia negli appunti. Il tuo caso d'uso ci aiuterà a priorizzare questa funzionalità.

Continua da Access Control Reference

Se stai utilizzando Riferimento al Controllo degli Accessi per pianificare dashboard e operazioni API, connettilo con API Overview per i dettagli di implementazione in API Overview Introduzione per i dettagli di implementazione in Introduzione Tasti API per i dettagli di implementazione in API Keys Dispositivi per i dettagli di implementazione in Dispositivi, e Pacchetti per i dettagli di implementazione in Pacchetti.