Access Control Reference

Capgo uses Include installazione, sincronizzazione e la guida markdown della fonte. To gestire cosa ogni membro del team può fare. I ruoli sono organizzati per ambito — dall'intera organizzazione fino a un singolo bundle.

Per una panoramica visiva della gestione dei membri nella dashboard, vedere Organizzazione.

---

Scopi dei ruoli

Ogni ruolo appartiene a uno scope che determina a cosa si riferisce il permesso di accesso.

Ambito	Si applica a	Esempio di utilizzo
Organizzazione	Tutta l'organizzazione e tutte le sue app	Il tuo co-fondatore riceve Super Amministratore; il tuo contabile riceve Gestore della fatturazione
App	Una singola app e i suoi canali	Un contractor che lavora su una sola app riceve Sviluppatore di app
Canale	Una singola versione del canale all'interno di un'app	Un ingegnere QA gestisce solo il staging canale
Pacchetto	Una versione del pacchetto singola	Un revisore ha bisogno di accesso in lettura a una versione di rilascio specifica

A un membro può essere assegnato 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

Il ruolo di organizzazione viene assegnato quando si invita un membro. Concedono l'accesso all'intera organizzazione.

Ruolo	Nome interno	Descrizione
Amministratore superiore	org_super_admin	Equivalente di proprietario. Controllo completo, incluso la possibilità di eliminare l'org, gestire la fatturazione e trasferire gli app. Viene automaticamente assegnato al creatore dell'org.
__CAPGO_KEEP_0__	org_admin	Amministrazione completa — gestisci membri, app, canali. Non è possibile eliminare l'organizzazione, aggiornare la fatturazione, trasferire le app o promuovere gli utenti a Super Admin.
Gestore fatturazione	org_billing_admin	Accesso solo fatturazione: visualizza e aggiorna le informazioni di fatturazione, le fatture e i registri di audit di fatturazione. Nessun accesso alle app o ai membri.
Membro	org_member	Accesso di sola lettura all'organizzazione e a tutte le sue app.

Matrice di autorizzazioni dell'organizzazione

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

Nota

I ruoli dell'organizzazione ereditano tutte le autorizzazioni dell'applicazione, del canale e del bundle che si trovano sotto di loro nella gerarchia. Un Amministratore Superiore può fare tutto ciò che un Amministratore dell'applicazione o Amministratore del canale può fare, su tutte le applicazioni e i canali.

---

Ruoli dell'applicazione

Limitati a un'applicazione singola. Utilizzali quando un membro del team dovrebbe lavorare solo su un'applicazione, non sull'intera organizzazione.

Funzione	Nome interno	Descrizione
Amministratore dell'app	app_admin	Controllo completo di un'app — canali, dispositivi, ruoli utente per l'app. Non è possibile cancellare o trasferire l'app (queste sono operazioni a livello di organizzazione).
Sviluppatore dell'app	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 dell'app	app_uploader	Accesso di sola lettura + caricamento di nuove versioni dei bundle.
Letture dell'app	app_reader	Solo lettura — statistiche, bundle, canali, log, dispositivi.

Matrice di autorizzazioni dell'app

Autorizzazione	Descrizione	Amministratore dell'applicazione	Sviluppatore dell'applicazione	Caricatore dell'applicazione	Letture dell'applicazione
app.read	Visualizza dettagli dell'applicazione, statistiche e metadati	✅	✅	✅	✅
app.update_settings	Modifica le impostazioni dell'applicazione	✅	❌	❌	❌
app.read_bundles	Visualizza l'elenco dei bundle caricati	✅	✅	✅	✅
app.upload_bundle	Carica una nuova versione del bundle	✅	✅	✅	❌
app.create_channel	Creazione di un nuovo canale	✅	❌	❌	❌
app.read_channels	Visualizza canali	✅	✅	✅	✅
app.read_logs	Visualizza registrazioni di aggiornamento di consegna	✅	✅	✅	✅
app.manage_devices	Assegna, sovrascrivi o disconnetti dispositivi	✅	✅	❌	❌
app.read_devices	Visualizza lista dispositivi	✅	✅	✅	✅
app.build_native	Avvia un build cloud nativo	✅	✅	❌	❌
app.read_audit	Visualizza 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 possono eseguirle, indipendentemente dai ruoli a livello di app.

---

Ruoli di canale

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

Nota

I ruoli di canale sono attualmente disponibili tramite API e CLI solo — non esiste una UI per assegnarli nel dashboard. Nel dashboard, utilizzare override delle autorizzazioni del canale al posto per regolare l'accesso al canale per utente.

Ruolo	Nome interno	Descrizione
Amministratore del canale	channel_admin	Pieno controllo di un canale: impostazioni, promuovere/riportare bundle, gestire dispositivi obbligatori.
Visualizzatore del canale	channel_reader	Letto solo — bundle corrente, storia, dispositivi obbligatori, registro di audit.

Matrice delle autorizzazioni del canale

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

---

Ruoli del bundle

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

Nota

Gli ruoli del pacchetto sono attualmente disponibili tramite API e CLI solo — non esiste una interfaccia utente 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 di bundle	bundle_reader	Accesso di sola lettura a un bundle specifico.

---

Override delle autorizzazioni del canale (Dashboard)

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

Gli override sono configurati dalla scheda Accesso del pannello di controllo dell'applicazione cliccando sul pulsante delle autorizzazioni dei canali (icona scudo) accanto a un utente. Vedi Organizzazione — Override delle autorizzazioni dei canali per una guida visiva passo dopo passo.

Autorizzazioni sovrapponibili

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
Assegna bundle	Imposta o modifica il bundle attivo sul canale	Ereditato dal ruolo dell'applicazione

Ogni autorizzazione può essere impostata su:

• Predefinito — eredita dal ruolo dell'applicazione (predefinito)
• Consenti — concede esplicitamente, indipendentemente dal ruolo dell'applicazione
• Neghi — nega esplicitamente, indipendentemente dal ruolo dell'applicazione

Ciò ti consente, ad esempio, di dare a un lettore di App la possibilità di associare bundle sul staging canale senza promuoverli a sviluppatore di App.

---

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 in turn 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)

Come funziona in pratica:

• Un Amministratore all'org level può fare tutto ciò che può fare un App Admin può, su ogni app nell'organizzazione.
• Un App Admin su un'app specifica può fare tutto ciò che un Channel Admin può, su ogni canale in quella app.
• Un App Developer può fare tutto ciò che un App Uploader può, più ancora.

La gerarchia fluisce solo in basso in basso — un channel_admin non acquisisce mai le autorizzazioni di livello organizzativo, anche se detiene anche un ruolo di livello applicazione.

---

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 una sola organizzazione — non può coprire più organizzazioni.
• I gruppi possono contenere legami di ruolo a qualsiasi ambito: organizzazione, app, canale o bundle. Ad esempio, un gruppo può essere assegnato il ruolo di sviluppatore dell'app su App A e il ruolo di amministratore del canale su il canale di App B. staging Quando vengono valutate le autorizzazioni di un utente, tutte le loro appartenenze ai gruppi vengono risolte in modo trasparente. Se qualsiasi dei loro gruppi concede la autorizzazione richiesta, l'accesso è consentito.
• Un utente può appartenere a
• i gruppi possono contenere legami di ruolo a __CAPGO_KEEP_0__ qualsiasi ambito __CAPGO_KEEP_1__ : organizzazione, app, canale o bundle. Ad esempio, un gruppo può essere assegnato il __CAPGO_KEEP_2__ ruolo di sviluppatore dell'app __CAPGO_KEEP_3__ su App A e il __CAPGO_KEEP_4__ ruolo di amministratore del canale __CAPGO_KEEP_5__ su il canale di App B. __CAPGO_KEEP_6__ Quando vengono valutate le autorizzazioni di un utente, tutte le loro appartenenze ai gruppi vengono risolte in modo trasparente. Se qualsiasi dei loro gruppi concede la autorizzazione richiesta, l'accesso è consentito. __CAPGO_KEEP_7__ Un utente può appartenere a __CAPGO_KEEP_8__ gruppi multipliLe autorizzazioni dei gruppi sono cumulative, ovvero le autorizzazioni dei gruppi e le autorizzazioni dei singoli utenti sono combinate.
• Gli accessi basati su gruppo si applicano solo ai principali utente — 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 sviluppatore a 3 app	15 vincoli di ruolo individuali	1 gruppo + 3 associazioni di ruolo
Qualcuno entra a far parte del team di QA	Aggiungi 3 associazioni di ruolo manualmente	Aggiungili al gruppo
Qualcuno lascia il team di QA	Rimuovi 3 associazioni di ruolo manualmente	Rimuovili dal gruppo

Gestisci gruppi tramite 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 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 la permessi (Super Amministratore o 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"
  }'

Cancella un gruppo

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

Cancellando un gruppo vengono anche eliminate tutte le relative associazioni 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. L'aggiunta di 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

Elimina 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 è nella nostra roadmap — 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 Riferimento al Controllo degli Accessi per pianificare il dashboard e le API operazioni, connettilo con Panoramica di API per i dettagli di implementazione in Panoramica di API Introduzione per i dettagli di implementazione in Introduzione Chiavi di API per i dettagli di implementazione in Chiavi di API Dispositivi per i dettagli di implementazione in Dispositivi, e Pacchetti per i dettagli di implementazione in Pacchetti.