Chiavi di API

API chiavi sono 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 con chiave API, authorization è accettato:

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

Alcuni endpoint accettano anche una testata di chiave dedicata. I Canali API accetta authorization o capgkeyutilizza uno di quei titoli per l'automazione del canale di anteprima.

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:

• Le chiavi API — Definisce le autorizzazioni di base della chiave per l'intera organizzazione (ad esempio, org_admin o org_member).
• Le chiavi API — Autorizzazioni per app (ad esempio, app_admin, app_developer, app_uploader, app_reader, or app_preview).

Se una chiave API ha vincoli di ruolo espliciti, solo questi vincoli vengono valutati per le verifiche di autorizzazione. I permessi personali del proprietario della chiave non sono ereditati dalla chiave.

Automazione del canale di anteprima

Lega app_preview solo all'app di anteprima per CI che crea un canale di anteprima temporaneo e non pubblico, carica e promuove un bundle, quindi 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'ID UUID dell'organizzazione di proprietà dell'app. app_id è l'ID UUID interno del record dell'app, non l'identificatore pubblico dell'app utilizzato dai comandi CLI (ad esempio, com.example.appLa lega rimane legata all'organizzazione anche quando la chiave non ha un ruolo organizzativo.

Livello dell'app app_preview 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 legame sulla nuova canale creata. Quel legame figlio concede channel.read, channel.promote_bundle, e channel.delete solamente per il canale che la chiave ha creato.

app_preview conserva app.read, quindi non è un'isolamento del canale-lettura rigoroso: la chiave può enumerare i metadati del canale nella selezionata app. Il legame figlio automatico limita mutazioni di ciclo di vita al canale che la chiave ha creato.

Capgo registra la chiave di anteprima dell'applicazione che ha caricato ogni bundle. La chiave può promuovere solo il proprio bundle in ogni canale di anteprima che crea. Non ha accesso al ciclo di vita di un canale esistente predefinito/main, un canale creato da un'altra chiave di anteprima o un bundle di un'altra chiave. Per questo workflow, omettere public e non utilizzare mai --default.

Usa channel delete <preview-channel> <public-app-id> --delete-bundle per la pulizia. Questa è una route di pulizia atomica, controllata di proprietà, per la preview; rimuove solo il canale di anteprima del chiama e il bundle correlato. app_preview non concede diritti generali bundle.delete.

For the dashboard setup and a complete CLI example, see Usa una chiave di anteprima per flussi di lavoro di anteprima.

Nota

Chiavi senza associazioni di ruolo ricadono in un sistema basato sulla versione legacy ("read, upload, write, allQueste modalità sono obsolete — utilizza invece i ruoli RBAC.

La permessione di creazione dell'organizzazione

Creare organizzazioni con una chiave API utilizza ora una permessione globale esplicita: org.create.

Questa permessione è separata dalle normali associazioni di ruolo per organizzazione/applicazione 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 anche avere una organizzazione-scopata org_admin o org_super_admin binding.
• Nuove API chiavi non ricevono org.create Abilita la creazione di organizzazioni Consenti la creazione di organizzazioni quando si crea o si modifica una chiave RBAC API nel pannello di controllo.
• Gli amministratori org scrittori/esistenti/super amministratori API hanno ricevuto le chiavi di riempimento org.create così le integrazioni esistenti possono continuare a creare organizzazioni.

Quando una API chiave crea un'organizzazione, Capgo assegna automaticamente quella stessa API chiave org_super_admin come chiave sull'organizzazione appena creata. Ciò consente all'integrazione di gestire l'organizzazione appena creata senza dover richiedere un ruolo di binding manuale separato.

Se crei una API chiave attraverso il API, includi 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 applica solo alla creazione di organizzazioni. La cancellazione di un'organizzazione richiede comunque la possibilità di eliminare l'organizzazione bersaglio, di solito tramite org_super_admin.

Chiavi sicure (Hashed)

Quando si crea una chiave sicura, il server genera il materiale di chiave e restituisce il valore in testo puro una volta. Viene memorizzato solo un hash. Ciò significa:

• La chiave in chiaro non può essere recuperato dopo la creazione.
• La regenerazione produce una nuova chiave di testo normale (visualizzata una volta) e aggiorna l'hash memorizzato.
• Si raccomandano 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 dell'organizzazione possono imporre:

• Scadenza obbligatoria (require_apikey_expiration)— Tutte le nuove chiavi devono avere un' scadenza.
• Maximum TTL (max_apikey_expiration_days) — L'invalidità non può essere oltre N giorni da ora.

Pratiche di sicurezza

1. Principio di minima autorizzazione: Assegna il ruolo più restrittivo che ancora consente alla tua integrazione di funzionare
2. Rotazione regolare: Rota i tuoi API chiavi periodicamente utilizzando la funzione di regenerazione
3. Memorizzazione sicuraRicorda di archiviare API in modo sicuro e non di esso in controllo di versione.
4. Utilizzo di chiavi hashate: Crea chiavi sicure (hashate) per le integrazioni di produzione
5. Setta Scadenza: Imposta sempre una data di scadenza per le chiavi utilizzate per l'accesso temporaneo o CI/CD
6. Restrizioni di Scope: Limita le chiavi a specifiche app con il ruolo minimo richiesto

Casi d'uso comuni

1. Integrazione CI/CD: Crea chiavi scolate a specifiche app con il app_uploader o app_developer : Crea chiavi scolate a specifiche app con il
2. PR Preview Canali: Utilizza app_preview su solo l'app di anteprima o le app quando il CI deve caricare un bundle, creare un canale temporaneo e pulire atomicamente il proprio canale e bundle.
3. Automazione della distribuzione: Utilizza le chiavi con il app_developer ruolo per i script di automazione della distribuzione.
4. Strumenti di monitoraggio: Crea chiavi con il app_reader ruolo per le integrazioni di monitoraggio esterne.
5. Accesso amministrativo: Utilizza le chiavi con il org_admin role sparingly for administrative tools.
6. Integrazioni di Terze PartiCreare chiavi limitate a specifiche app con il ruolo minimo richiesto.
7. Provisionamento dell'organizzazione: Utilizza un org_admin o org_super_admin Proseguisci con le chiavi __CAPGO_KEEP_0__ org.create Sottosezione intitolata “Proseguisci con le chiavi __CAPGO_KEEP_0__”

Se stai utilizzando le chiavi API

@__CAPGO_KEEP_0__/__CAPGO_KEEP_1__-login-social Chiavi API per pianificare l'autenticazione e i flussi di account, connettilo con @capgo/capacitor-login con social media per i dettagli di implementazione in @capgo/capacitor-login sociale, @capgo/capacitor-chiave di accesso per il dettaglio di implementazione in @capgo/capacitor-passkey @capgo/capacitor-nativo-biometrico per il dettaglio di implementazione in @capgo/capacitor-native-biometric Autenticazione a due fattori per il dettaglio di implementazione in Autenticazione a due fattori, e Single Sign-On (Enterprise) per il dettaglio di implementazione in SSO (Enterprise).