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 bundle.

Per una guida visiva alla gestione dei membri nel dashboard, vedere Organizzazione.

---

Ambiti 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	Il tuo co-fondatore ottiene Super Admin; il tuo contabile ottiene Billing Manager
App	Una singola 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
Bundle	Una versione del bundle	Un revisore ha 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 dell'organizzazione

Il ruolo viene assegnato quando si invita un membro. Concede l'accesso a tutta l'organizzazione.

Ruolo	Nome interno	Descrizione
Super Amministratore	org_super_admin	Uguale al proprietario. Controllo totale, incluso la possibilità di eliminare l'org, gestire la fatturazione e trasferire le app. Viene automaticamente assegnato al creatore dell'org.
Amministratore	org_admin	Amministrazione completa — gestire membri, app, canali. Non è possibile eliminare l'org, aggiornare la fatturazione, trasferire le app o promuovere gli utenti a Super Amministratore.
Gestore 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.
Membro	org_member	Accesso di sola lettura all'org e a tutti i suoi app.

Matrice di autorizzazioni dell'organizzazione

Autorizzazione	Descrizione	Super Amministratore	Amministratore	Gestore fatturazione	Membro
org.read	Visualizza l'organizzazione	✅	✅	✅	✅
org.update_settings	Modifica nome, logo, indirizzo 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

Il ruolo dell'organizzazione eredita tutte le autorizzazioni dell'app, del canale e del bundle sottostanti nella gerarchia. A Amministratore Superiore può fare tutto ciò che un Amministratore App o Amministratore Canale può fare, su tutti gli app e canali.

---

Ruoli App

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

Ruolo	Nome interno	Descrizione
Amministratore App	app_admin	Controllo completo di un'applicazione — canali, dispositivi, ruoli utente per l'applicazione. Non è possibile cancellare o trasferire l'applicazione (queste sono operazioni a livello di organizzazione).
Sviluppatore App	app_developer	Carica bundle, gestisci dispositivi, attiva costruzioni native, aggiorna impostazioni del canale. Nessuna cancellazione, nessuna modifica delle impostazioni dell'app, nessuna creazione di canali.
Caricatore App	app_uploader	Accesso di sola lettura + caricamento di nuove versioni del bundle.
Letture App	app_reader	Solo lettura — statistiche, bundle, canali, log, dispositivi.

Matrice di autorizzazioni dell'applicazione

Autorizzazione	Descrizione	Amministratore dell'app	Sviluppatore dell'app	Caricatore dell'app	Lettrice 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 i 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 UI per assegnarli nel dashboard. Nel dashboard, 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	Visualizza il canale e il suo bundle corrente	✅	✅
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 pacchetto	✅	✅
channel.promote_bundle	Imposta il pacchetto attivo sul canale	✅	❌
channel.rollback_bundle	Ritorna a un pacchetto precedente	✅	❌
channel.manage_forced_devices	Forza dispositivi specifici a questo canale	✅	❌
channel.read_forced_devices	Visualizza la lista dei dispositivi forzati	✅	✅
channel.read_audit	Visualizza il registro di attività del canale	✅	✅

---

Ruoli del pacchetto

Limitato a una sola versione del pacchetto. Raramente necessario — la maggior parte delle squadre utilizza invece i ruoli 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 di sola lettura a un bundle specifico.

---

Override delle autorizzazioni del canale (Pannello di controllo)

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

Il sovrapporsi sono configurati dalla scheda Accesso del'applicazione cliccando sul pulsante delle autorizzazioni del canale (icona scudo) accanto a un utente. Vedi Organizzazione — Sovrapposizioni delle autorizzazioni del canale per una guida visiva.

Le autorizzazioni sovraimponibili

Autonomia	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 (il predefinito)
• Consenti — concede esplicitamente, indipendentemente dal ruolo dell'applicazione
• Nega — blocca 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 This lets you, for example, give an App Reader the ability to associate bundles on the channel without promoting them to App Developer. 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 a livello di organizzazione può fare tutto ciò che un Amministratore dell'app può, su ogni app nell'organizzazione.
• Un App Admin può fare tutto ciò che può fare un Channel Admin su ogni canale di quell'app.
• Un App Developer può fare tutto ciò che può fare un App Uploader e ancora di più.

La gerarchia fluisce solo in basso — un channel_admin non acquisisce mai le autorizzazioni 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ù organizzazioni.
• I gruppi possono tenere 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 autorizzazioni basate sui gruppi si applicano solo a
• __CAPGO_KEEP_0__ principi di utente — API le chiavi non ereditano i ruoli di gruppo.

Quando utilizzare i gruppi

Caso di utilizzo	Senza gruppi	Con gruppi
5 ingegneri QA hanno bisogno di accesso al ruolo di 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	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 il permesso (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"
  }'

Elimina un gruppo

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

Eliminare un gruppo elimina anche tutti i relativi vincoli 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, utilizza i vincoli di ruolo API con principal_type: "group" e principal_id Assegna il gruppo UUID.

---

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

---

Assegnare 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 predefiniti coprono la maggior parte delle strutture di squadra. La creazione di ruoli personalizzati è nella nostra roadmap — se il tuo team ne ha bisogno, 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.