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. Canali API accetta authorization o capgkeyo canali accettano

; utilizza uno di questi header per l'automazione del canale di anteprima.

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 __CAPGO_KEEP_0__ utilizzano lo stesso sistema di controllo degli accessi basato sul ruolo (RBAC) delle account utente. Quando si crea o si gestisce le chiavi tramite l'applicazione web o __CAPGO_KEEP_1__, si assegna un ruolo a due livelli: Ruolo di organizzazione org_admin — Definisce i permessi di base della chiave per l'intera organizzazione (ad esempio, org_member).
• o Ruoli di applicazione app_admin, app_developer, app_uploader, app_readero oppure app_preview).

Se una chiave API ha vincoli di ruolo espliciti, Solo questi vincoli sono valutati per le verifiche di autorizzazione. Le autorizzazioni personali del proprietario della chiave non sono ereditate dalla chiave.

Automazione del canale di anteprima

Lega app_preview 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 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 proprietaria 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.app) La lega rimane legata all'organizzazione anche quando la chiave non ha ruoli di organizzazione.

L'app-level app_preview 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 sul canale appena creato. Quel legame figlio concede channel.read, channel.promote_bundle, e channel.delete solo per il canale che la chiave ha creato.

app_preview conserva app.read, quindi non è un'isolamento di lettura dei canali rigoroso: la chiave può enumerare i metadati dei canali selezionati nell'app. La legatura figlio automatica limita mutazioni della vita ciclo al canale che la chiave ha creato.

Capgo registra la chiave di anteprima dell'app che ha caricato ogni bundle. La chiave può promuovere solo il proprio bundle in ogni canale di anteprima che crea. Non ha accesso alla vita ciclo 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. Questo è un percorso di pulizia di anteprima atomico, controllato di proprietà; rimuove solo il canale di anteprima della chiave chiamante e il bundle correlato. 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 dell'applicazione per flussi di lavoro di anteprima.

Nota

Le chiavi senza legami di ruolo ricadono in un sistema basato su modi di vecchia generazione (read, upload, write, allQuesti modi sono obsoleti — utilizza invece i ruoli RBAC.

La permessione di creazione dell'organizzazione

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

Questa autorizzazione è separata dalle normali associazioni di ruolo per organizzazioni/applicazioni 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 un'organizzazione-scoperta org_admin o org_super_admin La chiave __CAPGO_KEEP_0__ deve essere abilitata
• Per creare organizzazioni con una chiave API: org.create La chiave __CAPGO_KEEP_0__ deve essere abilitata Per creare organizzazioni con una chiave __CAPGO_KEEP_0__: quando si crea o si modifica una chiave RBAC API nella dashboard.
• Existing write-capable org admin/super admin API keys were backfilled with org.create in modo che le integrazioni esistenti possano continuare a creare organizzazioni.

Quando una chiave API crea un'organizzazione, Capgo assegna automaticamente alla stessa chiave API 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 cancellazione sull'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. Viene memorizzato solo un hash. Ciò significa:

• La chiave di testo puro non può essere recuperata dopo la creazione.
• La regenerazione produce una nuova chiave di testo puro (visualizzata una volta) e aggiorna l'hash memorizzato.
• Si consiglia l'utilizzo di chiavi hashate per l'uso in produzione.

Alcune organizzazioni impongono le chiavi hashate tramite la enforce_hashed_api_keys Scadenza

Sezione intitolata “Scadenza”

Le politiche delle organizzazioni possono imporre:

Scadenza obbligatoria

• Regeneration produces a new plain-text key (shown once) and updates the stored hash. (require_apikey_expiration) — Tutti i nuovi chiavi devono avere un scadenza.
• Massimo TTL (max_apikey_expiration_days) — Lo scadenza non può essere più di N giorni da ora.

Pratiche di Sicurezza

1. Principio di Minima Autorità: Assegna il ruolo più restrittivo che ancora consente alla tua integrazione di funzionare
2. Rotazione Regolare: Rota le tue 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 HashateCreare chiavi sicure (hashate) per integrazioni di produzione
5. Crea scadenzaCreare sempre una data di scadenza per le chiavi utilizzate per l'accesso temporaneo o CI/CD
6. Restrizioni di ambitoLimitare le chiavi a specifiche app con il ruolo minimo richiesto

Utilizzo comune

1. Integrazione CI/CDSottosezione intitolata “Integrazione CI/CD” app_uploader o app_developer Creare chiavi scoprte a specifiche app con il
2. o: Utilizza app_preview su solo l'app di anteprima o 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 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 partiCreare chiavi limitate a specifiche app con il ruolo minimo richiesto.
7. Provisionamento dell'organizzazioneUsare un org_admin o org_super_admin Se desiderate scegliere tra diverse opzioni per il vostro progetto, potreste considerare l'uso di un'alternativa al nostro prodotto. Alcune delle nostre alternative includono Appflow, Capawesome e altre soluzioni che potrebbero soddisfare le vostre esigenze. org.create RBAC chiave con

Keep going from API Keys

Sottosezione intitolata “Continuate da qui dalle __CAPGO_KEEP_0__ Chiavi” Se state utilizzando le API Chiavi per pianificare l'autenticazione e le flussi di account, connettetelo con @__CAPGO_KEEP_0__/__CAPGO_KEEP_1__-login-social @capgo/capacitor-social-login per i dettagli di implementazione in @capgo/capacitor-login-social @capgo/capacitor-chiave-pass per i dettagli di implementazione in @capgo/capacitor-chiave-pass per i dettagli di implementazione in @capgo/capacitor-biometria-nativa per i dettagli di implementazione in @capgo/capacitor-biometria-nativa 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).