Chiavi API
Copia un prompt di configurazione con i passaggi di installazione e la guida markdown completa per questo plugin.
Le chiavi API servono per autenticare le richieste alla Capgo API. Le chiavi sono specifiche dell'organizzazione e possono avere ruoli RBAC assegnati per un controllo degli accessi granulare. Ogni chiave può anche avere una data di scadenza opzionale ed essere creata come chiave “secure” (hashed), dove il valore in chiaro viene mostrato una sola volta.
Usare una chiave API
Sezione intitolata “Utilizzo di una chiave API”Usa l'intestazione di autenticazione documentata per l'endpoint. Per le richieste con chiave API, authorization è accettata:
curl -H "authorization: YOUR_API_KEY" https://api.capgo.app/...Alcuni endpoint accettano anche un'intestazione di chiave dedicata. Il Canali API accetta authorization oppure capgkey; usa uno di questi header per l'automazione del canale di preview.
Permessi RBAC
Sezione intitolata “Permessi RBAC”Le chiavi API usano lo stesso sistema di controllo degli accessi basato sui ruoli (RBAC) degli account utente. Quando crei o gestisci chiavi tramite la web app o API, assegni i ruoli su due livelli:
- Ruolo dell'organizzazione — Definisce i permessi base della chiave per l'intera organizzazione (ad esempio,
org_adminoppureorg_member). - Ruoli dell'app — Permessi per singola app (ad esempio,
app_admin,app_developer,app_uploader,app_reader, oapp_preview).
Se una chiave API ha dei role binding espliciti, solo quei binding vengono valutati per i controlli dei permessi. La chiave non eredita i permessi personali del proprietario.
Automazione del canale preview
Sezione intitolata “Automazione del canale preview”Associa app_preview solo all'app di preview per la CI che crea un canale preview temporaneo e non pubblico, carica e promuove un bundle, poi elimina entrambi.
{ "name": "PR preview key", "hashed": true, "bindings": [ { "role_name": "app_preview", "scope_type": "app", "org_id": "<OWNING_ORG_UUID>", "app_id": "<APP_UUID>" } ]}org_id è l'UUID dell'organizzazione proprietaria dell'app. app_id è l'UUID interno del record dell'app, non l'app identifier pubblico usato dai comandi CLI (ad esempio, com.example.app). Il binding rimane legato all'organizzazione anche se la chiave non ha un ruolo a livello organizzativo.
Il ruolo a livello app app_preview il ruolo include solo app.read, app.read_bundles, app.upload_bundle, e app.create_channel. Quando quella chiave crea un canale, Capgo aggiunge automaticamente un channel_preview binding sul canale appena creato. Quel binding figlio concede channel.read, channel.promote_bundle, e channel.delete solo per il canale creato dalla chiave.
app_preview mantiene app.read, quindi non c'è un'isolamento rigoroso in lettura per canale: la chiave può enumerare i metadati dei canali nell'app selezionata. Il binding automatico dei figli limita mutazioni del ciclo di vita al canale creato dalla chiave.
Capgo registra la chiave App Preview che ha caricato ogni bundle. La chiave può promuovere solo il proprio bundle a ciascun canale di anteprima che crea. Non ha accesso al ciclo di vita dei canali per un canale default/main esistente, un canale creato da un'altra chiave di anteprima o un bundle di un'altra chiave. Per questo workflow, ometti public e non usare mai --default.
Usa channel delete <preview-channel> <public-app-id> --delete-bundle per la pulizia. Questo è un percorso di pulizia dell'anteprima atomico e con verifica di proprietà; rimuove solo il canale di anteprima della chiave chiamante e il bundle collegato. app_preview non concede accesso generico bundle.delete.
Per la configurazione della dashboard e un esempio completo di CLI, consulta Usa una chiave App Preview per i workflow di anteprima.

Permesso di creazione dell'organizzazione
Sezione intitolata “Permesso di creazione dell'organizzazione”La creazione di organizzazioni con una chiave API ora usa un permesso globale esplicito: org.create.
Questo permesso è separato dalle normali associazioni di ruolo org/app perché una nuova organizzazione non esiste ancora quando POST /organization/ viene chiamato. Per creare organizzazioni con una chiave API:
- La chiave API deve includere
org.createnellaglobal_permissions. - La stessa chiave API deve avere anche un binding attuale
org_adminoppureorg_super_adminbinding. - Le nuove chiavi API non ricevono
org.createdi default. Abilita Consenti la creazione di organizzazioni quando crei o modifichi una chiave API RBAC nel dashboard. - Le chiavi API esistenti per admin/super admin con permessi di scrittura sono state aggiornate con
org.createcosì le integrazioni esistenti possono continuare a creare organizzazioni.
Quando una chiave API crea un'organizzazione, Capgo assegna automaticamente la stessa chiave API come org_super_admin sull'organizzazione appena creata. Questo permette all'integrazione di gestire l'organizzazione che ha appena creato senza bisogno di un binding manuale separato del ruolo.
Se crei una chiave API tramite API, includi global_permissions accanto al binding dell'admin dell'organizzazione:
{ "name": "Provisioning key", "hashed": true, "bindings": [ { "role_name": "org_admin", "scope_type": "org", "org_id": "00000000-0000-0000-0000-000000000000" } ], "global_permissions": ["org.create"]}org.create si applica solo alla creazione di organizzazioni. L'eliminazione di un'organizzazione richiede comunque il permesso di eliminazione sull'organizzazione di destinazione, tipicamente tramite org_super_admin.
Chiavi sicure (hash)
Sezione intitolata “Chiavi sicure (hash)”Quando crei una chiave sicura, il server genera il materiale della chiave e restituisce il valore in chiaro una sola volta. Viene memorizzato solo un hash. Questo significa:
- La chiave in chiaro non può essere recuperata dopo la creazione.
- La rigenerazione crea una nuova chiave in testo semplice (visualizzata una sola volta) e aggiorna l'hash memorizzato.
- Per l'uso in produzione si consigliano le chiavi hash.
Alcune organizzazioni impongono chiavi hash tramite la enforce_hashed_api_keys policy dell'org.
Scadenza
Sezione intitolata “Expiration”Le chiavi possono avere una data di scadenza opzionale. Le chiavi scadute vengono rifiutate durante il controllo dei permessi.
Le policy dell'organizzazione possono imporre:
- Scadenza obbligatoria (
require_apikey_expiration) — Tutte le nuove chiavi devono avere una scadenza. - TTL massimo (
max_apikey_expiration_days) — La scadenza non può superare N giorni da oggi.
Best practice di sicurezza
Sezione intitolata “Best practice di sicurezza”- Principio del minimo privilegio: Assegna il ruolo più restrittivo che permetta comunque alla tua integrazione di funzionare
- Rotazione periodica: Ruota periodicamente le chiavi API utilizzando la funzione di rigenerazione
- Archiviazione sicura: Conserva le chiavi API al sicuro e non committarle mai nel version control
- Usa chiavi hash: Crea chiavi sicure (hash) per le integrazioni di produzione
- Imposta la scadenza: Imposta sempre una data di scadenza per le chiavi usate per accessi temporanei o CI/CD
- Limitazioni di scope: Limita le chiavi a app specifiche con il ruolo minimo richiesto
Casi d'uso comuni
Sezione intitolata “Casi d'uso comuni”- Integrazione CI/CD: Crea chiavi limitate ad app specifiche con il
app_uploaderoppureapp_developerruolo e imposta una data di scadenza. - Canali PR Preview: Usa
app_previewsolo sull'app o sulle app di preview quando la CI deve caricare un bundle, creare un canale temporaneo e ripulire in modo atomico il proprio canale e bundle. - Automazione del deployment: Usa chiavi con il
app_developerruolo per gli script di deployment automatizzati. - Strumenti di monitoraggio: Crea chiavi con il
app_readerruolo per integrazioni di monitoraggio esterne. - Accesso Admin: Usa chiavi con il
org_adminruolo con parsimonia per gli strumenti amministrativi. - Integrazioni di terze parti: Crea chiavi limitate ad app specifiche con il ruolo minimo richiesto.
- Provisioning dell'organizzazione: Usa un
org_adminoppureorg_super_adminChiave RBAC conorg.createsolo per automazioni fidate che devono creare organizzazioni.
Continua da API Keys
Sezione intitolata “Continua da API Keys”Se stai usando Chiavi API per pianificare i flussi di autenticazione e account, collegandolo a @capgo/capacitor-social-login per i dettagli di implementazione in @capgo/capacitor-social-login, @capgo/capacitor-passkey per i dettagli di implementazione in @capgo/capacitor-passkey, @capgo/capacitor-native-biometric per i dettagli di implementazione in @capgo/capacitor-native-biometric, Autenticazione a due fattori per i dettagli di implementazione in Two-factor authentication, e SSO (Enterprise) per i dettagli di implementazione in SSO (Enterprise).