Vai al contenuto

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.

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

La pagina mostra due sezioni:

  • Chiavi RBAC — Chiavi con ruoli assegnati (consigliate). Queste chiavi utilizzano il nuovo sistema di permessi basato sui ruoli.
  • Chiavi legacy — Chiavi più vecchie che utilizzano il semplice sistema basato su modalità (read, upload, write, all) senza assegnazione di ruoli.
Pagina di elenco delle chiavi API con sezioni RBAC e Legacy
  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 (facoltativo) — Scegli una data dopo la quale la chiave smette di funzionare. Alcune organizzazioni impongono una scadenza obbligatoria tramite policy.
Modulo di creazione della chiave API con nome, opzione chiave sicura e scadenza
  1. Scegli lo scope della chiave:

    • Accesso a livello di organizzazione — Seleziona un Ruolo dell'organizzazione per definire i permessi di base a livello di organizzazione. I ruoli disponibili dipendono dal tuo livello di ruolo:
      • Nessuna — Nessun accesso a livello di organizzazione.
      • Membro — Accesso in lettura di base 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 binding dell'app rimane collegato all'organizzazione proprietaria dell'app; questa modalità omette solo un ruolo RBAC a livello di organizzazione.
  2. Se la chiave deve creare organizzazioni tramite la API pubblica, abilita Consenti la creazione di organizzazioni.

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

  3. Per concedere l'accesso all'app:

    • Quando Limita questa chiave alle app selezionate è abilitato, scegli un'organizzazione sotto Organizzazioni per filtrare le app per visualizzarne le app. I binding dell'app selezionata restano associati alle organizzazioni di appartenenza; questo filtro non concede accesso a livello di organizzazione.
    • Clicca su ”+ Aggiungi App”, seleziona una o più app, quindi assegna un ruolo a ciascuna:
      • Lettore di app — Accesso in sola lettura all'app.
      • App Uploader — Può caricare nuovi bundle.
      • Sviluppatore App — Può caricare bundle, gestire 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 anteprima. Il canale riceve diritti automatici di ciclo di vita, limitati al canale, solo per questa chiave.
  4. Clicca su “Crea”.

  5. Se hai selezionato Crea chiave sicura, a modal displays the plain-text key. Copy it immediately — non potrà essere recuperata dopo la chiusura della modale.

Modale segreta chiave API monouso con pulsante di copia

Usa una chiave App Preview per i workflow di anteprima

Sezione intitolata “Usa una chiave App Preview per i flussi di anteprima”

Usa Anteprima App per CI che crea un canale di anteprima temporaneo e non pubblico, carica e promuove un bundle, quindi rimuove sia il canale sia 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 rimane associata alla sua organizzazione di appartenenza.
  3. Aggiungi solo l'app o le app utilizzate per le deploy di anteprima.
  4. Seleziona Anteprima App per ogni app selezionata.
  5. Crea una chiave sicura, imposta una data di scadenza quando appropriato e archiviala nel tuo secret manager CI.

Questa modalità solo app selezionate omette un ruolo a livello di organizzazione; non hai rimuove l'associazione con l'organizzazione. Ogni app_preview binding rimane limitato alla sua app selezionata e all'organizzazione di appartenenza di tale app.

ConcediPermessi e limiti
app_preview sull'app selezionataapp.read, app.read_bundles, app.upload_bundle, e app.create_channel.
Automatico channel_preview collegamentoQuando 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 collegamento automatico dei figli è una gestione boundary: non consente modifiche al ciclo di vita per i canali che la chiave non ha creato.

Capgo registra anche quale chiave App Preview ha effettuato l'upload di un bundle. La chiave può impostare solo il proprio bundle su ogni canale preview che crea e può fare cleanup di quella coppia insieme. Non riceve un binding di 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 job CI tipico, usa un nome di canale univoco per ogni pull request:

Finestra del terminale
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, esegue l'upload del bundle e lo promuove in un unico flusso. L'ultimo comando usa una route di cleanup atomica e ristretta: ha successo solo se la chiave possiede il canale preview e il relativo bundle collegato e non condiviso. Anteprima App non ha ancora permessi generali bundle.delete, quindi non può eliminare un bundle arbitrario.

Guarda il Riferimento controllo accessi per i limiti completi.

Clicca sul wrench icon (Gestisci) su qualsiasi chiave RBAC dell'elenco. Si apre la pagina di dettaglio della chiave, dove puoi:

  • Modificare la chiave nome.
  • Aggiorna il ruolo nell'organizzazione.
  • Abilitare o disabilitare Consenti la creazione di organizzazioni quando la chiave ha un ruolo Admin nell'organizzazione.
  • Aggiungere, rimuovere o modificare ruoli per app.

Clicca su “Salva modifiche” quando completato.

API key edit page with current role settings

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 semplici: il valore della chiave viene rigenerato lato server.

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

Conferma della rigenerazione della chiave API

Clicca sul icona cestino (Elimina) su qualsiasi chiave nell'elenco. Conferma l'eliminazione nella finestra di dialogo.

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

API key deletion confirmation dialog

Se vedi delle chiavi nella Chiavi legacy sezione (chiavi senza ruoli assegnati), usano il vecchio sistema di permessi basato su modalità (read, upload, write, all). Funzionano ancora, ma non sfruttano i permessi granulari RBAC.

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

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

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.