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 a testo puro viene visualizzato solo una volta.

Utilizzando una API chiave

Incolla la tua API chiave nel x-api-key testo di intestazione di ogni richiesta:

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

Il authorization Quando il valore è una chiave formattata come UUID API funziona, ma x-api-key è la intestazione raccomandata per tutti i tipi di chiave (inclusi chiavi sicure/hasheade).

Permessi RBAC

Le chiavi API utilizzano lo stesso sistema di controllo degli accessi basato sui ruoli (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, sono valutati solo questi vincoli 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 su modalità (read, upload, write, all). Queste modalità sono obsolete — utilizza 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 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 di produzione.

Alcune organizzazioni impongono le 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 delle organizzazioni possono imporre:

• Scadenza obbligatoria (require_apikey_expiration) — Tutte le nuove chiavi devono avere un' scadenza.
• TTL massimo (max_apikey_expiration_days) — La scadenza non può essere più di N giorni da ora.

Pratiche di sicurezza migliori

1. Principio di Minima Autorità: Assegna il ruolo più restrittivo che consenta ancora la funzionalità della tua integrazione
2. Rotazione Regolare: Rota i tuoi API periodicamente utilizzando la funzione di regenerazione
3. Memorizzazione Sicura: Memorizza i API in modo sicuro e non li 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. Restrizioni di Scope: Limita le chiavi ai determinati app con il ruolo minimo richiesto

Casi d'uso comuni

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