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

utilizza uno di questi intestazioni 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:

• __CAPGO_KEEP_0__ chiavi utilizzano lo stesso sistema di controllo degli accessi basato sul ruolo (RBAC) delle account utente. Quando si crea o si gestiscono le chiavi tramite l'app web o __CAPGO_KEEP_1__, si assegnano ruoli a due livelli: Ruolo di organizzazione org_admin — Definisce le autorizzazioni di base della chiave per l'intera organizzazione (ad esempio, org_member).
• o Ruoli dell'applicazione app_admin, app_developer, app_uploader, app_readero oppure app_preview).

Se una chiave API ha vincoli di ruolo espliciti, sono solo questi vincoli che vengono 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 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.

livello dell'app include solo app_preview ruolo include solo app.read, app.read_bundles, app.upload_bundle, e app.create_channel. Quando la 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 dei canali rigoroso: la chiave può enumerare i metadati dei canali selezionati nell'app. La legatura figlio automatica limita mutazioni del ciclo di vita ai canali 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 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 collegato. app_preview non concede diritti generici 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 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 un permesso globale esplicito: org.create.

Questo permesso è separato dalle normali associazioni di ruolo per organizzazione/applicazione perché una nuova organizzazione non esiste ancora quando POST /organization/ viene chiamato. 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 creazione di nuove chiavi __CAPGO_KEEP_0__ non riceve
• New API keys do not receive org.create Consenti la creazione di organizzazioni o 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 così le integrazioni esistenti possono continuare a creare organizzazioni.

Quando una chiave API crea un'organizzazione, Capgo assegna automaticamente alla stessa chiave API org_super_admin nella 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 della chiave e restituisce il valore in chiaro una volta sola. Solo una hash viene memorizzata. 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.
• Le chiavi crittate sono raccomandate per l'uso di produzione.

Alcune organizzazioni impongono le chiavi crittate tramite la enforce_hashed_api_keys Scadenza

Sezione intitolata “Scadenza”

Le politiche delle organizzazioni possono imporre:

Scadenza obbligatoria

• Section titled “Scadenza” (require_apikey_expiration — Tutti i nuovi chiavi devono avere una 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 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. Imposta 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 scritte per 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 desideri scoprire le alternative per l'aggiornamento in tempo reale di Capacitor, potresti considerare l'uso di un'altra soluzione. Alcune delle alternative più popolari includono Appflow e Capawesome. Queste soluzioni offrono funzionalità simili a Capacitor, ma con alcune differenze significative. Ad esempio, Appflow offre una maggiore flessibilità nella configurazione delle impostazioni di aggiornamento, mentre Capawesome si concentra sull'esperienza utente e sulla semplicità d'uso. org.create RBAC chiave con

Keep going from API Keys

Sottosezione intitolata “Continua da qui dalle __CAPGO_KEEP_0__ Chiavi” Se stai utilizzando le API Chiavi per pianificare l'autenticazione e le flussi di account, connettile con @capgo/capacitor-login-social 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).