API Chiavi

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.

Le chiavi API sono utilizzate per autenticare le richieste al __CAPGO_KEEP_1__ __CAPGO_KEEP_2__. 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.

Passa la tua API chiave nella x-api-key testa di ogni richiesta:

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

La authorization testa è anche accettata ma è principalmente destinata ai token JWT. Quando il valore è una chiave API formattata come UUID funziona, ma x-api-key è la testa raccomandata per tutti i tipi di chiavi (compresi le chiavi sicure/hashate).

Ruoli RBAC

API chiavi utilizzano lo stesso sistema di controllo degli accessi basato sul ruolo (RBAC) delle account utente. Quando si creano o si gestiscono le chiavi tramite l'app web, si assegnano ruoli a due livelli:

• Ruolo dell'organizzazione — Definisce le autorizzazioni di base della chiave per l'intera organizzazione (ad esempio org_admin, org_member).
• Ruoli dell'app — Autorizzazioni per-app facoltative (ad esempio app_admin, app_developer, app_uploader, app_reader).

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

Nota

Le chiavi senza vincoli di ruolo ricadono in un sistema basato sul livello di modalità (legacy mode)read, upload, write, allQuesti modi sono obsoleti — utilizza i ruoli RBAC al loro posto.

Permesso 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 l'app/organizzazione perché una nuova organizzazione non esiste ancora quando POST /organization/ è 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'associazione attuale di tipo organizzazione-scoperto org_admin o org_super_admin associazione.
• Le nuove chiavi API non ricevono org.create di default. Abilita Consenti di creare organizzazioni quando si crea o si modifica una chiave RBAC API nel dashboard.
• Le chiavi esistenti amministratore/super amministratore con diritti di scrittura API sono state riempite con 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 che ha appena creato senza dover richiedere un ruolo di binding manuale separato.

Se si crea 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 (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 in chiaro non può essere recuperata dopo la creazione.
• La regenerazione produce una nuova chiave in chiaro (mostrata una volta sola) e aggiorna l'hash memorizzato.
• Le chiavi hashate sono raccomandate per l'uso in produzione.

Alcune organizzazioni impongono chiavi hashate tramite la enforce_hashed_api_keys politica dell'organizzazione.

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) — Tutti i nuovi chiavi devono avere un' scadenza.
• TTL massimo (max_apikey_expiration_days) — La scadenza non può essere più lontana di N giorni da ora.

Pratiche di sicurezza migliori

1. Principio di minima autorizzazione: Assegna il ruolo più restrittivo che consenta ancora alla tua integrazione di funzionare
2. Rotazione regolare: Rota periodicamente le tue API chiavi utilizzando la funzione di regenerazione
3. Archiviazione sicura: Salva API chiavi in modo sicuro e non le commetti mai nel controllo delle versioni
4. Usa 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

Uso Comune

1. Integrazione CI/CD: Crea chiavi scolate a specifiche app con il app_uploader o app_developer ruolo e impostare una data di scadenza
2. Automazione di distribuzione: Utilizza chiavi con il app_developer ruolo per i script di distribuzione automatizzati
3. Strumenti di monitoraggio: Crea chiavi con il app_reader ruolo per le integrazioni di monitoraggio esterne
4. Accesso amministrativo: Utilizza chiavi con il org_admin ruolo con parsimonia per strumenti amministrativi
5. Integrazioni di terze parti: Crea chiavi limitate a specifiche app con il ruolo minimo richiesto
6. Provisionamento dell'organizzazione: Utilizza un org_admin o org_super_admin 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 le autenticazioni e i flussi di account, connettilo con @capgo/capacitor-login-sociale per i dettagli di implementazione in @capgo/capacitor-login-sociale, @capgo/capacitor-passkey per il dettaglio di implementazione in @capgo/capacitor-passkey, @capgo/capacitor-native-biometric 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 SSO (azienda) per il dettaglio di implementazione in SSO (azienda).