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 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 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 i permessi di base della chiave all'interno dell'intera organizzazione (ad esempio, o org_admin Ruoli dell'app org_member).
• — Permessi 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 pacchetto, quindi elimina 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'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

__CAPGO_KEEP_0__ app_preview __CAPGO_KEEP_0__ app.read, app.read_bundles, app.upload_bundleWhen si 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 non è un isolamento di lettura dei canali rigoroso: la chiave può enumerare i metadati del canale selezionato nell'applicazione. channel.read, channel.promote_bundleil legame figlio limita le mutazioni del ciclo di vita del canale al canale creato dalla chiave. channel.delete __CAPGO_KEEP_0__ registra la chiave di anteprima dell'applicazione che ha caricato ogni bundle.

app_preview la chiave può promuovere solo il proprio bundle in ogni canale di anteprima che crea. app.readnon ha accesso al ciclo di vita del canale per un canale predefinito/main esistente, un canale creato da un'altra chiave di anteprima o un bundle di un'altra chiave. per questo flusso di lavoro, omettere e non utilizzare mai Usare

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 Usa una chiave di anteprima per flussi di lavoro di anteprima.

Nota

Le chiavi senza legami di ruolo ricadono in un sistema basato su modalità (read, upload, write, all) deprecato — utilizza invece le autorizzazioni di ruolo RBAC.

Autorizzazione alla creazione di organizzazioni

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

This permission è separata dalle normali associazioni di ruolo dell'organizzazione/app perché una nuova organizzazione non esiste ancora quando POST /organization/ è 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 una 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 pannello di controllo.
• Il chiavi di amministratore/super amministratore di organizzazione scritta esistente sono stati riempiti con API org.create così le integrazioni esistenti possono continuare a creare organizzazioni.

Quando una chiave API crea un'organizzazione, Capgo assegna automaticamente quella 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 crei una chiave API 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 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 (Hashed)

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 semplice (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 dell'organizzazione 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 funzione di regenerazione
3. Memorizzazione Sicura: Memorizza le API chiavi in modo sicuro e non le commettere mai al controllo delle versioni
4. Utilizzo di Chiavi Hashate: Crea chiavi sicure (hashate) per le integrazioni di produzione
5. Imposta 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 scoprte 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 quando 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 ha bisogno di 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 (azienda) per i dettagli di implementazione in SSO (azienda).