Chiavi API

Le chiavi API utilizzano il controllo degli accessi basato sui ruoli (RBAC). Una chiave può avere un ruolo a livello di organizzazione, binding limitati alla singola app, o entrambi. Ogni binding rimane associato all'organizzazione proprietaria dell'app. Per seguire il principio del minimo privilegio, limita una chiave alle sole app selezionate invece di assegnare un ruolo a livello di organizzazione.

Dove si gestiscono le chiavi API?

Naviga in Impostazioni > Organizzazione > Chiavi API in console.capgo.app/settings/organization/api-keys.

La pagina mostra due sezioni:

• Chiavi RBAC — Chiavi con ruoli assegnati (consigliato). Queste chiavi utilizzano il nuovo sistema di permessi basato su ruoli.
• Chiavi Legacy — Chiavi precedenti che utilizzano il vecchio sistema basato su modalità (read, upload, write, all) senza assegnazione di ruoli.

Come creare una nuova chiave API?

1. Clicca sul ”+” pulsante in alto nella tabella delle chiavi RBAC.

2. Compila le Informazioni della chiave:

   • Nome (obbligatorio) — Un'etichetta descrittiva per la chiave (ad esempio, “CI/CD Deploy” o “Monitoring Read-Only”).
   • Crea chiave sicura (opzionale) — Se selezionato, la chiave viene hashata lato server. La chiave in chiaro viene mostrata una sola volta dopo la creazione e non potrà essere recuperata in seguito.
   • Imposta data di scadenza (opzionale) — Scegli una data di scadenza per la chiave. Alcune organizzazioni impongono la scadenza tramite policy.

3. Scegli lo scope della chiave:

   • Accesso a livello di organizzazione — Seleziona un Ruolo dell'organizzazione per definire i permessi base dell'organizzazione. I ruoli disponibili dipendono dal tuo livello di permessi:
     • Nessuna — Nessun accesso a livello di organizzazione.
     • Member — Accesso di sola lettura all'organizzazione.
     • Admin — Accesso amministrativo completo all'organizzazione e a tutte le sue app.
   • Accesso solo alle app — Abilita Limita questa chiave alle app selezionate. Ogni app binding rimane collegato all'organizzazione proprietaria di quell'app; questa modalità omette solo il ruolo RBAC a livello di organizzazione.

4. Se la chiave deve creare organizzazioni tramite il API pubblico, abilita Consenti la creazione di organizzazioni.

   Questo aggiunge il org.create globale. La chiave necessita anche di un org_admin o org_super_admin collegamento. Nella dashboard, selezionando Admin crea il org_admin binding. Quando questa chiave crea una nuova organizzazione, Capgo assegna automaticamente la chiave come Super Admin a quella nuova organizzazione.

5. Per concedere l'accesso alle app:

   • Quando Limita questa chiave alle app selezionate è abilitato, scegli un'organizzazione sotto Organizzazioni per filtrare le app per visualizzarne le app. I binding delle app selezionate rimangono associati alle rispettive organizzazioni; questo filtro non concede l'accesso a tutta l'organizzazione.
   • Clicca su ”+ Aggiungi App”, seleziona una o più app, quindi assegna un ruolo a ciascuna:
     • App Reader — Accesso in sola lettura all'app.
     • Uploader App — Può caricare nuovi bundle.
     • Sviluppatore App — Può caricare bundle, gestire i dispositivi, avviare native build e aggiornare le impostazioni del canale.
     • Admin App — Accesso completo all'app.
     • Anteprima App — Anteprima del ciclo di vita CI/CD: carica un bundle e crea un canale di preview. Il canale riceve permessi automatici limitati a quel canale solo per questa chiave.

6. Clicca su “Crea”.

7. Se hai selezionato Crea chiave sicura, viene visualizzata una modale con la chiave in chiaro. Copiala subito — non potrà più essere recuperata dopo la chiusura della modale.

Usa una chiave App Preview per i workflow di anteprima

Usa Anteprima App per la CI che crea un canale di anteprima temporaneo e non pubblico, effettua l'upload e la promozione di un bundle, per poi rimuovere sia il canale che il bundle. Non ha accesso al ciclo di vita di un canale predefinito o principale esistente.

1. Crea una chiave RBAC e abilita Limita questa chiave alle app selezionate.
2. Sotto Organizzazioni per filtrare le app, seleziona l'organizzazione per visualizzarne le app; ogni app selezionata rimarrà associata alla propria organizzazione.
3. Aggiungi solo l'app o le app utilizzate per i deployment di preview.
4. Seleziona Anteprima App per ogni app selezionata.
5. Crea una chiave sicura, imposta una data di scadenza se necessario e salvala nel secret manager della tua CI.

Questa modalità limitata alle app selezionate evita un ruolo a livello di organizzazione; essa hai rimuove l'associazione con l'organizzazione. Ogni app_preview binding rimane limitato alla sua app selezionata e all'organizzazione di appartenenza di quell'app.

Concedi	Permessi e limiti
app_preview sull'app selezionata	app.read, app.read_bundles, app.upload_bundle, e app.create_channel.
Automatico channel_preview collegamento	Quando questa chiave crea un canale, Capgo assegna automaticamente alla chiave channel.read, channel.promote_bundle, e channel.delete solo per quel canale.

app_preview mantiene app.read, quindi la chiave può elencare i metadati del canale nell'app selezionata. Il binding automatico dei figli è una gestione boundary: non permette mutazioni del ciclo di vita per i canali non creati dalla chiave.

Capgo registra anche quale chiave App Preview ha caricato un bundle. La chiave può impostare solo il proprio bundle su ogni canale preview creato e può gestire la pulizia di tale coppia. Non riceve un binding del canale per un canale default o main esistente, per un canale creato da un'altra chiave preview o per il bundle di un'altra chiave.

Per un tipico job CI, usa un nome canale unico per ogni pull request:

APP_ID="com.example.app"
PREVIEW_CHANNEL="pr-123"
BUNDLE_VERSION="1.2.3-pr.123"

npx @capgo/cli@latest bundle upload "$APP_ID" \
  --apikey "$CAPGO_API_KEY" \
  --path ./dist \
  --channel "$PREVIEW_CHANNEL" \
  --bundle "$BUNDLE_VERSION"

npx @capgo/cli@latest channel delete "$PREVIEW_CHANNEL" "$APP_ID" \
  --apikey "$CAPGO_API_KEY" \
  --delete-bundle \
  --success-if-not-found

Per un nuovo canale, bundle upload --channel crea il canale, carica il bundle e lo promuove in un unico flusso. L'ultimo comando utilizza una rotta di cleanup atomica ristretta: ha successo solo se la chiave possiede il canale preview e il relativo bundle non condiviso. Anteprima App non ha ancora permessi bundle.delete, quindi non può eliminare un bundle arbitrario.

Attenzione

Usa un nuovo canale pr-<number> non pubblico. Non passare --default, --self-assignopzioni di rollout o --delete-linked-bundle-on-upload a questo workflow. Una Anteprima App key non può promuovere, eliminare o modificare un canale default/main esistente, il canale di un'altra preview key o il bundle di un'altra key. Revocare o far scadere l'app binding rimuove anche l'accesso al ciclo di vita della key.

Guarda il Riferimento controllo accessi per i limiti completi.

Come gestire (modificare) una API key?

Clicca sul wrench icon (Gestisci) su qualsiasi chiave RBAC nell'elenco. Questo apre la pagina dei dettagli della chiave dove puoi:

• Cambiare la chiave nome.
• Aggiornare il ruolo dell'organizzazione.
• Abilitare o disabilitare Consenti la creazione di organizzazioni quando la chiave ha un ruolo Admin nell'organizzazione.
• Aggiungere, rimuovere o cambiare ruoli per singola app.

Clicca su “Salva modifiche” when done.

Come rigenerare una chiave API?

Per rigenerare il valore segreto di una chiave API, clicca sull'icona icona refresh (Regenerate) su una qualsiasi chiave nell'elenco.

Apparirà una finestra di conferma. Dopo aver confermato:

• Per chiavi sicure (hashed): Viene generata una nuova chiave in chiaro e mostrata una sola volta in un modal. Copiala subito.
• Per chiavi in chiaro: Il valore della chiave viene rigenerato lato server.

Qualsiasi integrazione che utilizza il vecchio valore della chiave smetterà immediatamente di funzionare.

Come eliminare una chiave API?

Clicca sul icona del cestino (Delete) su una qualsiasi chiave nell'elenco. Conferma l'eliminazione nel dialog.

La chiave viene revocata immediatamente: qualsiasi richiesta che la utilizzi fallirà.

Chiavi legacy

Se vedi delle chiavi nella Chiavi Legacy sezione (chiavi senza assegnazione di ruoli), queste utilizzano il vecchio sistema di permessi basato su modalità (read, upload, write, all). Funzionano ancora, ma non beneficiano dei permessi granulari RBAC.

Le chiavi legacy possono essere rigenerate o eliminate dall'elenco, ma non possono essere modificate per aggiungere ruoli RBAC. Ti consigliamo di creare nuove chiavi RBAC e di eliminare quelle legacy quando possibile.

Se hai bisogno di gestire direttamente le chiavi legacy, puoi comunque accedervi su console.capgo.app/dashboard/apikeys. Questa pagina è deprecata e verrà rimossa in un aggiornamento futuro.

Continua da API Keys

Se stai usando Chiavi API per pianificare le operazioni della dashboard e di API, collegalo a Panoramica API per i dettagli di implementazione in Panoramica di API, Introduzione per i dettagli di implementazione in Introduzione, Chiavi API per i dettagli di implementazione delle chiavi API, Dispositivi per i dettagli di implementazione in Devices, e Bundle per il dettaglio di implementazione in Bundles.