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.

Utilizzando una API chiave

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

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

Il titolo è anche accettato ma è principalmente destinato ai token JWT. Quando il valore è una chiave formattata come UUID (__CAPGO_KEEP_0__), funziona, ma authorization header is also accepted but is primarily intended for JWT tokens. When the value is a UUID-formatted API key it works, but x-api-key Permessi RBAC

Sezione 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, you assign roles at two levels:

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

If an API key has explicit role bindings, Permessi RBAC sono valutati per le verifiche di autorizzazione. I permessi personali del proprietario della chiave non sono ereditati dalla chiave.

Nota

Le chiavi senza legami di ruolo ricadono in un sistema basato su modalità (read, upload, write, all). Queste modalità sono obsolete — utilizzare invece i ruoli RBAC.

Chiavi sicure (Hashed)

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 in chiaro non può essere recuperata dopo la creazione.
• La regenerazione produce una nuova chiave di testo piana (visualizzata una volta) e aggiorna l'hash memorizzato.
• Si consiglia l'utilizzo di chiavi hashate per l'uso di produzione.

Alcune organizzazioni impongono 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_expirationScadenza obbligatoria) — Tutte le nuove chiavi devono avere una scadenza.
• Scadenza massima (max_apikey_expiration_daysScadenza massima) — La scadenza non può essere superiore a N giorni rispetto a oggi.

Pratiche di Sicurezza

1. Principio di Minima Autorità: Assegna il ruolo più restrittivo che consenta ancora alla tua integrazione di funzionare
2. Rotazione Regolare: Rota periodicamente i tuoi API chiavi 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. Impostazione di Scadenza: Imposta sempre una data di scadenza per le chiavi utilizzate per l'accesso temporaneo o CI/CD
6. Ambito delle restrizioni: Limitare le chiavi a specifiche app con il ruolo minimo richiesto

Casi d'uso comuni

1. Integrazione CI/CD: Creare chiavi scritte per specifiche app con il app_uploader o app_developer ruolo, e impostare una data di scadenza
2. Automazione del dispiegamento: Utilizzare le chiavi con il app_developer ruolo per i script di automazione del dispiegamento
3. Strumenti di monitoraggio: Crea chiavi con il app_reader ruolo per le integrazioni di monitoraggio esterno
4. Accesso amministrativo: Utilizza le chiavi con il org_admin ruolo con parsimonia per gli strumenti amministrativi
5. Integrazioni di terze parti: Crea chiavi limitate a specifiche app con il ruolo richiesto minimo

Continua da API Chiavi

Se stai utilizzando API Chiavi per pianificare l'autenticazione e i flussi di account, connettilo con @capgo/capacitor-social-login per i dettagli di implementazione in @capgo/capacitor-social-login @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).