Chiavi API

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.

Utilizzo di una chiave API

Usa l'header di autenticazione documentato dall'endpoint. Per le richieste con chiave API, authorization è accettato:

curl -H "authorization: YOUR_API_KEY" https://api.capgo.app/...

Alcuni endpoint accettano anche un header dedicato. Il Canali API accetta authorization o capgkey; usa uno di questi header per l'automazione del preview-channel.

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_admin o org_member).
• Ruoli dell'app — Permessi per singola app (ad esempio, app_admin, app_developer, app_uploader, app_reader, o app_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

Vincola app_preview solo all'app di preview per la CI che crea un canale preview temporaneo e non pubblico, effettua l'upload e la promozione di un bundle, per poi eliminarli 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'identificativo 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.

A livello di 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 nuovo canale creato. Quel binding figlio garantisce 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 stretto per la lettura dei canali: 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 effettuato l'upload di ogni bundle. La chiave può promuovere solo il proprio bundle nei canali preview che crea. Non ha accesso al ciclo di vita dei canali per un canale default/main esistente, per un canale creato da un'altra chiave preview o per il 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. Questa è una rotta di cleanup atomica con controllo della proprietà; rimuove solo il canale preview e il bundle collegato alla chiave chiamante. app_preview non concede permessi generici bundle.delete.

Per la configurazione della dashboard e un esempio completo di CLI, consulta Usa una chiave App Preview per i workflow di anteprima.

Nota

Le chiavi senza binding di ruolo utilizzano un sistema legacy basato su modalità (read, upload, write, all). Queste modalità sono deprecate — usa invece i ruoli RBAC.

Permesso di creazione organizzazione

La creazione di organizzazioni con una chiave API ora usa un permesso globale esplicito: org.create.

Questo permesso è separato dai normali binding di ruolo org/app perché una nuova organizzazione non esiste ancora quando POST /organization/ viene chiamata. Per creare organizzazioni con una chiave API:

• La chiave API deve includere org.create in global_permissions.
• La stessa chiave API deve avere anche un binding attuale org_admin o org_super_admin binding.
• Le nuove chiavi API non ricevono org.create di 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.create così 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 la API, includi global_permissions insieme al binding dell'admin dell'org:

{
  "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. Per eliminare un'organizzazione è comunque necessario il permesso di delete sull'org di destinazione, solitamente tramite org_super_admin.

Chiavi Secure (Hashed)

Quando crei una chiave sicura, il server genera il materiale della chiave e restituisce il valore in chiaro una sola volta. Viene memorizzato solo l'hash. Ciò significa:

• La chiave in plain-text non può essere recuperata dopo la creazione.
• La rigenerazione produce una nuova chiave in plain-text (mostrata una sola volta) e aggiorna l'hash memorizzato.
• Le chiavi hashed sono consigliate per l'uso in produzione.

Alcune organizzazioni impongono chiavi hash tramite la enforce_hashed_api_keys org policy.

Scadenza

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 i N giorni da oggi.

Best practice di sicurezza

1. Principio del minimo privilegio: Assegna il ruolo più restrittivo possibile per il funzionamento dell'integrazione
2. Rotazione regolare: Ruota periodicamente le chiavi API tramite la funzione di rigenerazione
3. Archiviazione sicura: Conserva le chiavi API in modo sicuro e non caricarle mai nel version control
4. Usa chiavi hashed: Crea chiavi sicure (hashed) per le integrazioni in produzione
5. Imposta la scadenza: Imposta sempre una data di scadenza per le chiavi usate per accessi temporanei o CI/CD
6. Restrizioni di scope: Limita le chiavi a specifiche app con il ruolo minimo necessario

Casi d'uso comuni

1. Integrazione CI/CD: Crea chiavi con scope per app specifiche tramite il app_uploader o app_developer ruolo e imposta una data di scadenza.
2. Canali PR Preview: Usa app_preview solo sull'app (o sulle app) di preview quando la CI deve fare l'upload di un bundle, creare un canale temporaneo e pulire in modo atomico il proprio canale e bundle.
3. Automazione del deployment: Usa chiavi con il app_developer ruolo per gli script di deployment automatizzati.
4. Strumenti di Monitoring: Crea chiavi con il app_reader ruolo per integrazioni di monitoring esterne.
5. Accesso Admin: Usa chiavi con il org_admin ruolo con moderazione per tool amministrativi.
6. Integrazioni di terze parti: Crea chiavi limitate a app specifiche con il ruolo minimo richiesto.
7. Provisioning dell'organizzazione: Usa una chiave org_admin o org_super_admin Chiave RBAC con org.create solo per automazioni affidabili che devono creare organizzazioni.

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 dell'autenticazione a due fattori, e SSO (Enterprise) per i dettagli di implementazione dell'SSO (Enterprise).