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.

For a visual walkthrough of managing members in the dashboard, see 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	Tutta l'org e tutti i suoi app	Tuoi co-fondatori ottengono Super Admin; il tuo contabile ottiene Billing Manager
App	Una sola app e i suoi canali	Un contractor che lavora su un'app riceve il ruolo di App Developer
Canale	Un singolo canale all'interno di un'app	Un ingegnere QA gestisce solo il staging canale
Pacchetto	Una versione del pacchetto	Un revisore ha bisogno di accesso in 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 dell'organizzazione

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

Ruolo	Nome interno	Descrizione
Super Amministratore	org_super_admin	Equivalente di proprietario. Controllo completo, compreso la cancellazione dell'org, la gestione della fatturazione e la trasferimento degli 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 gli 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 agli app o membri.
Membro	org_member	Accesso di sola lettura all'org e a tutti i suoi app.

Matrice delle autorizzazioni dell'org

Autorizzazione	Descrizione	Super Amministratore	Amministratore	Gestore fatturazione	Membro
org.read	Visualizza l'organizzazione	✅	✅	✅	✅
org.update_settings	Modifica nome, logo, email di gestione dell'org	✅	✅	❌	❌
org.delete	Elimina permanentemente l'organizzazione	✅	❌	❌	❌
org.read_members	Visualizza la lista dei 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 corrente	✅	✅	✅	❌
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

I ruoli dell'organizzazione ereditano tutti i permessi dell'app, del canale e del bundle sottostanti nella gerarchia. Amministratore Superiore può fare tutto ciò che può fare un Amministratore dell'App o Amministratore del Canale può fare, su tutti gli app e i canali.

---

Ruoli dell'App

Limitato a un singolo app. Utilizzare questi quando un membro del team dovrebbe lavorare solo su un'app, non sull'intera organizzazione.

Ruolo	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.
Lettore dell'app	app_reader	Solo lettura — statistiche, bundle, canali, log, dispositivi.

Matrice di permessi dell'app

Permesso	Descrizione	Amministratore dell'app	Sviluppatore 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 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 canali	✅	✅	✅	✅
app.read_logs	Visualizza i registri di consegna degli aggiornamenti	✅	✅	✅	✅
app.manage_devices	Assegna, sovrascrivi 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 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

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

Nota

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

Ruolo	Nome interno	Descrizione
Amministratore del canale	channel_admin	Tutti i controlli su un canale: impostazioni, promuovi/riporta bundle, gestisci dispositivi obbligatori.
Visualizza il canale	channel_reader	Letture 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	View the channel and its current bundle	✅	✅
channel.update_settings	Modifica le impostazioni del canale (tasti di piattaforma, politica di aggiornamento…)	✅	❌
channel.delete	Cancella il canale	✅	❌
channel.read_history	Visualizza la storia 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

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

Nota

Le funzioni di bundle sono attualmente disponibili tramite API e CLI solo — non esiste una interfaccia utente per assegnarle nel pannello di controllo.

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

---

Override delle autorizzazioni del canale (Pannello di controllo)

In dashboard, l'accesso ai canali è determinato dal ruolo dell'applicazione dell'utente di default. Per un controllo più dettagliato, puoi sovraimporre autorizzazioni di canale specifiche per utente o gruppo senza modificare il loro ruolo dell'applicazione.

Il sovrapposizionamento è configurato dalla scheda Accesso del tuo app, cliccando sul pulsante delle autorizzazioni del canale (icona scudo) accanto a un utente. Vedi Organizzazione — Sovrapposizioni delle autorizzazioni dei canali per una guida visiva.

Sovrapposizioni delle autorizzazioni

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	Ereditato dal ruolo dell'applicazione

Ogni autorizzazione può essere impostata su:

• Predefinito — ereditare dal ruolo dell'applicazione (il 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 di App la possibilità di associare bundle sul canale senza promuoverli a sviluppatore di App. staging Gerarchia dei ruoli

---

Sezione intitolata “Gerarchia dei ruoli”

eredita tutti i permessi __CAPGO_KEEP_0__ di tutte le sue figlie. Ciò significa che un org_admin può fare tutto ciò che un app_admin può, il che a sua volta può fare tutto ciò che un channel_admin può, 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 Amministratore all'org level può fare tutto ciò che un App Amministratore 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 può fare, più ancora.

L'organigramma fluisce solo in basso — un channel_admin non acquisisce mai i 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 una sola organizzazione — non può coprire più di un'org.
• I gruppi possono avere vincoli di ruolo. qualsiasi ambito: organizzazione, app, canale o bundle. Ad esempio, un gruppo può essere assegnato il ruolo di App Sviluppatore 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 sue appartenenze ai gruppi vengono risolte in modo trasparente. Se qualsiasi dei suoi gruppi concede la autorizzazione richiesta, l'accesso è consentito.
• Un utente può appartenere a
• gruppi diversi , e le autorizzazioni da tutti i gruppi sono additive.Gli accessi basati sui gruppi si applicano solo a
• __CAPGO_KEEP_0__ utenti principali — API le chiavi non ereditano i ruoli di gruppo.

Quando utilizzare i gruppi

Scenario	Senza gruppi	Con gruppi
5 ingegneri QA hanno bisogno di accesso sviluppatore a 3 app	15 legami di ruolo individuali	1 gruppo + 3 legami di ruolo
Qualcuno entra a far parte del team QA	Aggiungere 3 legami di ruolo manualmente	Aggiungili al gruppo
Qualcuno lascia l'equipe di QA	Elimina 3 legami di ruolo manualmente	Eliminali dal gruppo

Gestisci 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 permesso.

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

Elimina un gruppo

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

Eliminare un gruppo elimina anche tutte le sue 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. 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 impostare sul UUID del gruppo.

---

Assegnare ruoli tramite API

Elencare 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
  }
]

Invitare 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 ruoli tramite CLI

Elenco organizzazioni

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

Elenco membri

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

Nota

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

---

Ruoli personalizzati

Il ruoli integrati coprono la struttura di squadra più comune. La creazione di ruoli personalizzati è nel nostro piano di lavoro — se il tuo team ha bisogno di questo, 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 le operazioni di dashboard e API , 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.