Riferimento al controllo degli accessi

Capgo uses Include installazione, sincronizzazione e la guida markdown della fonte. per 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 nel pannello di controllo, vedere Organizzazione.

---

Ambiti dei ruoli

Ogni ruolo appartiene a un ambito che determina a cosa si riferisce l'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 fatturazione
App	Una singola app e i suoi canali	Un contrattista che lavora su un'app riceve Sviluppatore app
Canale	Un singolo canale all'interno di un'app	Un ingegnere QA gestisce solo il staging canale
Pacchetto	Una versione del pacchetto singolo	Un revisore ha bisogno di accesso in lettura a una versione di rilascio 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 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. Concesso automaticamente al creatore dell'org.
— ad esempio, un ruolo di organizzazione, un ruolo su App A e un ruolo diverso su App B.	org_admin	Amministrazione completa — gestisci membri, app, canali. Non è possibile cancellare l'organizzazione, aggiornare la fatturazione, trasferire le app o promuovere gli utenti a Super Amministratore.
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 Amministratore	Amministratore	Gestore fatturazione	Membro
org.read	Visualizza l'organizzazione	✅	✅	✅	✅
org.update_settings	Modifica nome, logo e indirizzo email di gestione dell'organizzazione	✅	✅	❌	❌
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 attuale	✅	✅	✅	❌
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 tutte le autorizzazioni degli app, canali e bundle ruoli 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 tutti gli app e canali.

---

Ruoli dell'applicazione

Limitati a un'applicazione singola. Utilizzali 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 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 permessi dell'app

Autorizzazione	Descrizione	Amministratore dell'app	Sviluppatore dell'app	Caricatore dell'app	Letture dell'app
app.read	Visualizza dettagli dell'app, statistiche e metadati	✅	✅	✅	✅
app.update_settings	Modifica le impostazioni dell'app	✅	❌	❌	❌
app.read_bundles	Visualizza l'elenco dei pacchetti caricati	✅	✅	✅	✅
app.upload_bundle	Carica una nuova versione del pacchetto	✅	✅	✅	❌
app.create_channel	Crea un nuovo canale	✅	❌	❌	❌
app.read_channels	Visualizza canali	✅	✅	✅	✅
app.read_logs	Visualizza registrazioni di aggiornamento	✅	✅	✅	✅
app.manage_devices	Assegna, sovrascrivi o disconnetti dispositivi	✅	✅	❌	❌
app.read_devices	Visualizza lista dispositivi	✅	✅	✅	✅
app.build_native	Trasmetti 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

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

Nota

I ruoli di canale sono attualmente disponibili solo tramite API e CLI — non esiste una interfaccia utente per assegnarli nel dashboard. Nel dashboard, utilizzare 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, promuovere/riportare bundle, gestire dispositivi obbligatori.
Visualizzatore del canale	channel_reader	Solo lettura — bundle corrente, storia, dispositivi obbligatori, registro degli accessi.

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	Elimina il canale	✅	❌
channel.delete	Visualizza la cronologia delle assegnazioni del bundle	✅	❌
channel.read_history	Imposta il bundle attivo sul canale	✅	✅
channel.promote_bundle	Ritorna a 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	✅	✅

---

__CAPGO_KEEP_0__

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

Nota

Gli attuali ruoli del pacchetto sono 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 (Pannello di controllo)

Nel pannello 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 loro ruolo dell'applicazione.

Le sovrascritture sono configurate dalla scheda Accesso del pannello di controllo cliccando sul pulsante delle autorizzazioni dei canali (icona scudo) accanto a un utente. Vedi Organizzazione — Soprascrittura delle autorizzazioni dei canali per una guida visiva.

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
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 (la predefinita)
• Consenti — concede esplicitamente, indipendentemente dal ruolo dell'applicazione
• Negati — nega esplicitamente, indipendentemente dal ruolo dell'applicazione

Ciò ti consente, ad esempio, di dare a un lettore dell'app l'abilità di associare bundle sul staging canale senza promuoverli a sviluppatore dell'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 un app_admin può, che in turn 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 nella pratica:

• Un Amministratore a livello di organizzazione può fare tutto ciò che un Amministratore App può, su ogni app nell'organizzazione.
• Un Amministratore App su un'app specifica può fare tutto ciò che un Amministratore Canale può, su ogni canale in quella app.
• Un Sviluppatore App può fare tutto ciò che un Caricatore App può, più ancora.

The gerarchia fluisce solo in basso verso – 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ù di un'org.
• I gruppi possono memorizzare le associazioni di ruolo a qualsiasi ambito: org, app, canale o bundle. Ad esempio, un gruppo può essere assegnato il Ruolo sviluppatore di App ruolo sul Canale amministratore del 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
• __CAPGO_KEEP_0__ gruppi multipli, e le autorizzazioni da tutti i gruppi sono additive.
• Le autorizzazioni basate sui gruppi si applicano solo ai principali utente — le chiavi API non ereditano ruoli di gruppo.

Quando utilizzare i gruppi

Scenario	Senza gruppi	Con gruppi
5 ingegneri QA hanno bisogno di accesso sviluppatore a 3 app	15 vincoli di ruolo individuali	1 gruppo + 3 legami di ruolo
Qualcuno entra a far parte del team di QA	Aggiungi 3 legami di ruolo manualmente	Aggiungili al gruppo
Qualcuno lascia il team di QA	Rimuovi 3 legami 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"
  }'

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

---

Ruoli personalizzati

I ruoli integrati coprono la struttura di squadra più comune. La creazione di ruoli personalizzati è nel nostro piano di lavoro — se il tuo team ne ha bisogno, contattaciIl tuo caso d'uso aiuterà direttamente a priorizzare questa funzionalità.