API Chiavi

Le chiavi API vengono utilizzate per autenticare le richieste a Capgo API. Ciascuna chiave può avere autorizzazioni (modalità) diverse per controllare i livelli di accesso. Le chiavi sono specifiche dell’organizzazione e devono essere gestite con attenzione poiché concedono l’accesso alle tue risorse Capgo.

Modalità chiave

lettura: può solo leggere i dati, non sono consentite modifiche
carica: può leggere, modificare e caricare nuovi bundle
write: può leggere, modificare dati e caricare pacchetti
all: accesso completo a tutte le operazioni

Le modalità chiave seguono uno schema graduale/graduale. Se disponi di una chiave di caricamento e poi crei una chiave di scrittura, la chiave di scrittura sarà in grado di fare tutto ciò che potrebbe fare la chiave di caricamento. Dai un’occhiata al diagramma seguente per comprendere meglio come funzionano le chiavi API.

Un diagramma che spiega come funziona la chiave API

Sottochiavi con diritti limitati

Puoi creare sottochiavi con accesso limitato ad app o organizzazioni specifiche. Ciò è utile per limitare l’accesso a determinate risorse pur consentendo operazioni su altre. Utilizza i parametri limited_to_apps e limited_to_orgs durante la creazione di una chiave per definire queste restrizioni.

Chiavi crittografate

Puoi creare chiavi API crittografate (con hash) per una maggiore sicurezza. Quando crei una chiave crittografata:

La chiave viene sottoposta ad hashing utilizzando SHA-256 prima di essere archiviata nel database
La chiave semplice viene restituita solo una volta nella risposta di creazione: salvala immediatamente
La chiave non può essere recuperata o visualizzata nuovamente dopo la creazione
Se perdi una chiave crittografata, devi crearne una nuova

Utilizza il parametro hashed: true durante la creazione di una chiave per abilitare la crittografia. Questo è l’approccio consigliato per gli ambienti di produzione.

Scadenza chiave

Le chiavi API possono avere una data di scadenza per limitare la finestra di esposizione se una chiave viene compromessa. Quando viene impostata una data di scadenza:

La chiave smette di funzionare dopo la data e l’ora specificate
Le richieste che utilizzano chiavi scadute verranno rifiutate con un errore
Le chiavi scadute vengono automaticamente cancellate dopo 30 giorni

Le organizzazioni possono applicare policy di scadenza:

Richiedi scadenza: tutte le chiavi API devono avere una data di scadenza
Periodo di scadenza massimo: limita l’intervallo nel futuro in cui è possibile impostare una data di scadenza

Migliori pratiche di sicurezza

Principio del privilegio minimo: utilizza sempre la modalità più restrittiva che consenta comunque il funzionamento della tua integrazione
Utilizza chiavi crittografate: crea chiavi hash per la produzione per proteggerti dalle violazioni del database
Imposta date di scadenza: utilizza le date di scadenza per limitare la durata delle tue chiavi
Rotazione regolare: ruota periodicamente le tue chiavi API
Archiviazione sicura: archivia le chiavi API in modo sicuro e non impegnarle mai nel controllo della versione
Monitoraggio: monitora l’utilizzo delle chiavi API e revoca immediatamente eventuali chiavi compromesse
Sottochiavi limitate: utilizza sottochiavi con diritti limitati per integrazioni specifiche per ridurre al minimo i rischi

Endpoint

OTTIENI

https://api.capgo.app/apikey/

Recupera tutte le chiavi API associate al tuo account.

Tipo di risposta

interface ApiKey {
  created_at: string | null
  id: number
  key: string | null  // null for encrypted keys
  mode: 'read' | 'write' | 'upload' | 'all'
  name: string
  updated_at: string | null
  user_id: string
  limited_to_apps?: string[]
  limited_to_orgs?: string[]
  expires_at?: string | null  // ISO 8601 date, null means never expires
}
```> **Nota**: per le chiavi crittografate, il campo `key` sarà `null` nelle risposte GET poiché la chiave semplice viene mostrata solo una volta durante la creazione.

#### Richiesta di esempio

```bash
curl -H "authorization: your-api-key" https://api.capgo.app/apikey/

Esempio di risposta

{
  "data": [
    {
      "id": 1,
      "key": "ak_123...",
      "mode": "read",
      "name": "CI/CD Read Key",
      "created_at": "2024-01-01T00:00:00Z",
      "updated_at": "2024-01-01T00:00:00Z",
      "user_id": "user_123"
    },
    {
      "id": 2,
      "key": "ak_456...",
      "mode": "upload",
      "name": "Deploy Bot",
      "created_at": "2024-01-02T00:00:00Z",
      "updated_at": "2024-01-02T00:00:00Z",
      "user_id": "user_123",
      "limited_to_apps": ["com.demo.app"]
    }
  ]
}

POST

https://api.capgo.app/apikey/

Crea una nuova chiave API per un’organizzazione specifica.

Richiedi corpo

interface ApiKeyCreate {
  name: string
  mode: 'read' | 'write' | 'upload' | 'all'
  limited_to_apps?: string[]
  limited_to_orgs?: string[]
  hashed?: boolean       // Create an encrypted key (recommended for production)
  expires_at?: string    // ISO 8601 date for key expiration
}

Esempio di richiesta (chiave standard)

curl -X POST \
  -H "authorization: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Limited Read Key",
    "mode": "read",
    "limited_to_apps": ["com.demo.app"]
  }' \
  https://api.capgo.app/apikey/

Esempio di richiesta (chiave crittografata con scadenza)

curl -X POST \
  -H "authorization: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Secure CI Key",
    "mode": "upload",
    "hashed": true,
    "expires_at": "2025-06-01T00:00:00Z"
  }' \
  https://api.capgo.app/apikey/

Esempio di risposta (tasto standard)

{
  "apikey": {
    "id": 3,
    "key": "ak_789...",
    "mode": "read",
    "name": "Limited Read Key",
    "created_at": "2024-02-12T00:00:00Z",
    "user_id": "user_123",
    "limited_to_apps": ["com.demo.app"]
  }
}

Esempio di risposta (chiave crittografata)

{
  "apikey": {
    "id": 4,
    "key": "ak_abc123...",
    "mode": "upload",
    "name": "Secure CI Key",
    "created_at": "2024-02-12T00:00:00Z",
    "user_id": "user_123",
    "expires_at": "2025-06-01T00:00:00Z"
  }
}

Importante: per le chiavi crittografate, il valore key in questa risposta è l’unica volta in cui vedrai la chiave semplice. Salvalo immediatamente in un luogo sicuro. Le successive richieste GET restituiranno null per il campo key.

ELIMINA

https://api.capgo.app/apikey/:id/

Elimina una chiave API esistente. Usalo per revocare immediatamente l’accesso.

Parametri

id: l’ID della chiave API da eliminare (identificatore numerico, non la stringa della chiave stessa)

Richiesta di esempio

curl -X DELETE -H "authorization: your-api-key" https://api.capgo.app/apikey/1/

Risposta riuscita

{
  "success": true
}

Casi d’uso comuni

Integrazione CI/CD: crea chiavi di sola lettura per le pipeline CI per verificare lo stato della distribuzione
Automazione della distribuzione: utilizza le chiavi della modalità di caricamento per gli script di distribuzione automatizzati
Strumenti di monitoraggio: utilizza i tasti della modalità di lettura per le integrazioni di monitoraggio esterno
Accesso amministratore: utilizzare tutte le chiavi di modalità con parsimonia per gli strumenti amministrativi
Accesso limitato: crea sottochiavi con diritti limitati su app o organizzazioni specifiche per integrazioni di terze parti

Gestione degli errori

Scenari di errore comuni e relative risposte:

// Invalid mode
{
  "error": "Invalid mode specified. Must be one of: read, write, upload, all",
  "status": "KO"
}

// Key not found
{
  "error": "API key not found",
  "status": "KO"
}

// Permission denied
{
  "error": "Insufficient permissions to manage API keys",
  "status": "KO"
}

// Expired API key used for authentication
{
  "error": "API key has expired",
  "status": "KO"
}

// Invalid expiration date (in the past)
{
  "error": "Expiration date must be in the future",
  "status": "KO"
}

// Organization requires expiration
{
  "error": "Organization policy requires an expiration date for API keys",
  "status": "KO"
}

// Expiration exceeds organization limit
{
  "error": "Expiration date exceeds organization maximum of 90 days",
  "status": "KO"
}