API Chiavi

API chiavi vengono utilizzate per autenticare le richieste al Capgo API. Le chiavi sono specifiche dell'organizzazione e possono essere assegnate ruoli RBAC per un controllo di accesso fine-granulare. Ogni chiave può anche avere una data di scadenza facoltativa e può essere creata come una “chiave sicura” (hashata) dove il valore in chiaro viene visualizzato solo una volta.

Utilizzare una API chiave

Utilizzare l'intestazione di autenticazione documentata dall'endpoint. Per le richieste API-chiave, authorization è accettato:

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

Alcuni endpoint accettano anche una testata di chiave dedicata. I Canali API accettano authorization o utilizza uno di questi header per l'automazione del canale di anteprima. capgkeyPermessi RBAC

Sottosezione intitolata “Permessi RBAC”

API keys use the same role-based access control (RBAC) system as user accounts. When creating or managing keys through the web app or API, you assign roles at two levels:

• — Definisce le autorizzazioni di base della chiave all'interno dell'intera organizzazione (ad esempio, o org_admin Ruoli dell'app org_member).
• — Autorizzazioni per-app (ad esempio, , o app_admin, app_developer, app_uploader, app_readerSe una chiave __CAPGO_KEEP_0__ ha vincoli di ruolo espliciti, app_preview).

If an API key has explicit role bindings, sono valutate solo per le verifiche di autorizzazione. I permessi personali del proprietario della chiave non sono ereditati dalla chiave. Canale di anteprima dell'automazione

Sottosezione intitolata “Automazione del canale di anteprima”

si lega solo all'app di anteprima per il CI che crea un canale di anteprima temporaneo e non pubblico, carica e promuove un bundle, quindi cancella entrambi. app_preview Copia nella clipboard

{
  "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'ID UUID interno del record dell'app, non l'identificatore pubblico dell'app utilizzato dai comandi __CAPGO_KEEP_0__ (ad esempio, app_id is the app record’s internal UUID, not the public app identifier used by CLI commands (for example, com.example.appil ruolo dell'app include solo

i permessi dell'organizzazione app_preview i permessi dell'organizzazione app.read, app.read_bundles, app.upload_bundleWhen il key crea un canale, __CAPGO_KEEP_0__ aggiunge automaticamente un legame al canale appena creato. app.create_channel. When that key creates a channel, Capgo automatically adds a channel_preview il key non mantiene il canale, quindi non è una isolazione di lettura del canale rigorosa: il key può enumerare i metadati del canale nella selezionata app. channel.read, channel.promote_bundleil legame figlio automatico limita le mutazioni del ciclo di vita del canale al canale creato dal key. channel.delete __CAPGO_KEEP_0__ registra il key di anteprima dell'app che ha caricato ogni bundle. Il key può promuovere solo il proprio bundle in ogni canale di anteprima che crea.

app_preview il key non ha accesso al ciclo di vita del canale per un canale predefinito/main creato da un altro key di anteprima o per un bundle di un altro key. app.readOmettere e non utilizzare mai "e" per questo workflow. Usare e

Capgo records the App Preview key that uploaded each bundle. The key can promote only its own bundle to each preview channel it creates. It has no channel lifecycle access to an existing default/main channel, a channel created by another preview key, or another key’s bundle. For this workflow, omit public e --default.

e channel delete <preview-channel> <public-app-id> --delete-bundle per la pulizia. Questo è un percorso di pulizia di anteprima atomico, controllato di proprietà; rimuove solo il canale di anteprima della chiave chiamante e il bundle collegato. app_preview non concede diritti generali bundle.delete.

Per la configurazione del dashboard e un esempio completo di CLI, vedere Utilizzare una chiave di anteprima dell'applicazione per flussi di lavoro di anteprima.

Nota

Le chiavi senza vincoli di ruolo ricadono in un sistema basato su modalità (read, upload, write, all). Queste modalità sono obsolete — utilizzare invece le autorizzazioni di ruolo RBAC.

Autorizzazione alla creazione di organizzazioni

La creazione di organizzazioni con una chiave API utilizza ora un' autorizzazione globale esplicita: org.create.

Questa autorizzazione è separata dalle normali associazioni di ruolo dell'organizzazione/app perché una nuova organizzazione non esiste ancora quando viene chiamata. POST /organization/ Per creare organizzazioni con una chiave API:

• La chiave API deve includere org.create in global_permissions.
• La stessa chiave API deve anche avere un'organizzazione-scoperta attuale org_admin o org_super_admin legame.
• Le nuove chiavi API non ricevono org.create di default. Abilita Consenti la creazione di organizzazioni quando si crea o si modifica una chiave RBAC API nel dashboard.
• Existing write-capable org admin/super admin API keys were backfilled with org.create So 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 Sulla nuova organizzazione appena creata. Ciò consente all'integrazione di gestire l'organizzazione appena creata senza dover richiedere un ruolo di binding manuale separato.

Se si crea una chiave API attraverso il API, includere global_permissions insieme al binding di amministratore di 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. La cancellazione di un'organizzazione richiede comunque la possibilità di cancellare l'organizzazione di destinazione, tipicamente attraverso org_super_admin.

Chiavi sicure (Hashate)

Quando si crea una chiave sicura, il server genera il materiale di chiave e restituisce il valore in chiaro una volta sola. Solo una hash viene memorizzata. Ciò significa:

• La chiave in chiaro non può essere recuperata Dopo la creazione.
• La regenerazione produce una nuova chiave di testo puro (visualizzata una volta) e aggiorna l'hash memorizzato.
• Sono raccomandate le chiavi hashate per l'uso in produzione.

Alcune organizzazioni impongono le chiavi hashate tramite la enforce_hashed_api_keys politica dell'org.

Scadenza

Le chiavi possono avere una data di scadenza facoltativa. Le chiavi scadute vengono rifiutate al livello di controllo delle autorizzazioni.

Le politiche delle organizzazioni possono imporre:

• Scadenza obbligatoria (require_apikey_expiration — Tutte le nuove chiavi devono avere un' scadenza.
• Massimo TTL (max_apikey_expiration_days — La scadenza non può essere più lontana di N giorni da ora.

Pratiche di Sicurezza

1. Principio di Minima Autorità: Assegna il ruolo più restrittivo che consenta ancora la funzionalità della tua integrazione
2. Rotazione Regolare: Rota i tuoi API chiavi periodicamente utilizzando la funzionalità di regenerazione
3. Magazzino Sicuro: Archivia le API chiavi in modo sicuro e non le commettere mai al controllo delle versioni
4. Utilizza Chiavi Hashate: Crea chiavi sicure (hashate) per le integrazioni di produzione
5. Stabilisci Scadenza: Imposta sempre una data di scadenza per le chiavi utilizzate per l'accesso temporaneo o CI/CD
6. Restrizioni di ambito: Limita le chiavi a specifiche app con il ruolo minimo richiesto

Uso comune

1. Integrazione CI/CD: Crea chiavi scolate a specifiche app con il app_uploader o app_developer ruolo e imposta una data di scadenza.
2. Canali di anteprima dei PR: Utilizza app_preview su solo l'app di anteprima o app di anteprima quando il CI deve caricare un bundle, creare un canale temporaneo e pulire atomicamente il proprio canale e bundle.
3. Automazione di Deploy: Utilizza le chiavi con il app_developer ruolo per i script di deploy automatizzati.
4. Strumenti di Monitoraggio: Crea le chiavi con il app_reader ruolo per le integrazioni di monitoraggio esterne.
5. Accesso Amministrativo: Utilizza le chiavi con il org_admin ruolo con parsimonia per gli strumenti amministrativi.
6. Integrazioni di Terze Parti: Crea le chiavi limitate a specifiche app con il ruolo minimo richiesto.
7. Provisionamento dell'Organizzazione: Utilizza un org_admin o org_super_admin La chiave RBAC con org.create solo per l'automazione affidabile che deve creare organizzazioni.

Continua da API Chiavi

Se stai utilizzando API Chiavi per pianificare l'autenticazione e le flussi di account, connettilo con @capgo/capacitor-login-social per i dettagli di implementazione in @capgo/capacitor-login-social, @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 Autenticazione a due fattori, e SSO (aziendale) per i dettagli di implementazione in SSO (aziendale).