API Chiavi

API le 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 mostrato 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 chiave di intestazione dedicata. Il Canali API accetta authorization o capgkeyo

Canali __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'app web o __CAPGO_KEEP_1__, si assegna un ruolo a due livelli:

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:

• o Ruoli di app org_admin — Autorizzazioni per-app (ad esempio, org_member).
• RBAC Permissions Sezione intitolata “Autorizzazioni RBAC” 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. I permessi personali del proprietario della chiave non sono ereditati 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 un ruolo organizzativo.

The app-level 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 sul canale appena creato. 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 di lettura del canale rigoroso: la chiave può enumerare i metadati del canale selezionato nell'applicazione. La legatura figlia automatica limita mutazioni di ciclo di vita 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 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 flusso di lavoro, 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 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 dell'applicazione per flussi di lavoro di anteprima.

Nota

Le chiavi senza vincoli di ruolo ricadono in un sistema basato su modalità di vecchia generazione (read, upload, write, allQueste modalità sono obsolete — utilizza invece i ruoli RBAC.

La possibilità di creare un'organizzazione

La creazione di organizzazioni con una chiave API ora utilizza 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 viene chiamata. Per creare organizzazioni con una chiave __CAPGO_KEEP_0__: POST /organization/ La chiave API deve includere

• The API key must include org.create La stessa chiave __CAPGO_KEEP_0__ deve anche avere un'organizzazione-scoperta attuale global_permissions.
• The same API key must also have a current organization-scoped org_admin La chiave __CAPGO_KEEP_0__ deve essere inclusa org_super_admin La stessa chiave __CAPGO_KEEP_0__ deve anche avere un'organizzazione-scoperta attuale
• New API keys do not receive org.create La chiave __CAPGO_KEEP_0__ deve essere inclusa La stessa chiave __CAPGO_KEEP_0__ deve anche avere un'organizzazione-scoperta attuale 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 vincolo di ruolo manuale separato.

Se si crea una chiave API attraverso il API, includere global_permissions insieme al vincolo di amministratore di 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. La cancellazione di un'organizzazione richiede comunque il permesso 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. Solo un hash viene memorizzato. 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'utilizzo 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

• Section titled “Scadenza” (require_apikey_expiration) — Tutte le nuove chiavi devono avere un scadenza.
• Massimo TTL (max_apikey_expiration_days) — Lo scadenza non può essere oltre 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 scadenzaSempre impostare 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

Casi d'uso comuni

1. Integrazione CI/CD: Creare chiavi scoping specifiche app con il app_uploader o app_developer : Creare chiavi scoping specifiche app con il
2. e impostare una data di scadenza.: Utilizza app_preview su solo l'app di anteprima o app quando il CI deve caricare un bundle, creare un canale temporaneo e pulire automaticamente il proprio canale e bundle.
3. Automazione della distribuzione: Utilizza le chiavi con il app_developer ruolo per gli 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 parti: Crea chiavi limitate a specifiche app con il ruolo minimo richiesto.
7. Provisionamento dell'organizzazione: Utilizza un org_admin o org_super_admin : Utilizza un'alternativa per ottenere le stesse prestazioni di Capacitor, senza la necessità di aggiornamenti in tempo reale. Capacitor offre una soluzione di aggiornamento in tempo reale, ma se non è necessario, puoi utilizzare un'alternativa per ridurre i costi e migliorare la scalabilità. Inoltre, le alternative possono offrire funzionalità aggiuntive e una maggiore flessibilità. org.create : Utilizza un'alternativa per ottenere le stesse prestazioni di Appflow, senza la necessità di aggiornamenti in tempo reale. Appflow offre una soluzione di aggiornamento in tempo reale, ma se non è necessario, puoi utilizzare un'alternativa per ridurre i costi e migliorare la scalabilità. Inoltre, le alternative possono offrire funzionalità aggiuntive e una maggiore flessibilità.

Keep going from API Keys

: Chiave RBAC con API Keys : Continua da __CAPGO_KEEP_0__ Chiavi : Se stai utilizzando capgo Chiavi per pianificare l'autenticazione e le flussi di account, connettilo con @capgo/capacitor-login sociale per i dettagli di implementazione in @capgo/capacitor-login-social @capgo/capacitor-chiave-pass per i dettagli di implementazione in @capgo/capacitor-chiave-pass @capgo/capacitor-biometria-nativa per i dettagli di implementazione in @capgo/capacitor-biometria-nativa L'autenticazione a due fattori per i dettagli di implementazione in L'autenticazione a due fattori, e L'accesso SSO (Enterprise) per i dettagli di implementazione in L'accesso SSO (Enterprise).