Autenticazione

Ogni richiesta all’API REST CodeCourier deve essere autenticata con una chiave API con scope di progetto. Questa pagina spiega come creare le chiavi, come includerle nelle richieste e come gestire gli errori di autenticazione.

Creare una chiave API

1. Apri il tuo progetto nel dashboard CodeCourier.
2. Vai in Project Settings e apri la sezione API Keys.
3. Clicca su Generate New Keye fornisci un nome descrittivo (ad es., «CI Pipeline» o «LLM Agent»).
4. Il sistema mostra la chiave completa esattamente una volta. Copiala subito e conservala in modo sicuro. CodeCourier memorizza solo un hash SHA-256 - la chiave grezza non può essere recuperata.

Puoi anche creare chiavi programmaticamente tramite la Project API: POST /api/v1/project/api-keys/generate.

Formato della chiave API

Tutte le chiavi API di progetto seguono un formato di prefisso riconoscibile:

cc_live_a1b2c3d4e5f6...   # production key
cc_test_a1b2c3d4e5f6...   # test/staging key

Le chiavi sono precedute dal prefisso cc_live_ (produzione) o cc_test_ (ambienti di test). Il prefisso più i primi 8 caratteri fungono da prefisso di visualizzazione mostrato nel dashboard. La chiave completa è una lunga stringa casuale usata per l’autenticazione.

Usare la chiave API

Includi la chiave come bearer token nell’header Authorization di ogni richiesta:

curl -X GET \
  -H "Authorization: Bearer cc_live_a1b2c3d4..." \
  -H "Content-Type: application/json" \
  https://<your-deployment>.convex.site/api/v1/project

Per le richieste POST con un body JSON:

curl -X POST \
  -H "Authorization: Bearer cc_live_a1b2c3d4..." \
  -H "Content-Type: application/json" \
  -d '{"name": "My Workflow"}' \
  https://<your-deployment>.convex.site/api/v1/workflows/create

URL di base

L’URL di base è l’endpoint HTTP Action del tuo deployment Convex:

https://<your-deployment>.convex.site/api/v1/

Errore comune: Usa .convex.site - NON .convex.cloud. Il dominio .convex.cloud è l’URL WebSocket dei dati Convex interno e non servirà le richieste dell’API REST. Solo .convex.site espone le HTTP Action.

Puoi trovare il nome del tuo deployment nel dashboard Convex (ad es., happy-animal-123), dando un URL di base di https://happy-animal-123.convex.site/api/v1/.

Proprietà delle chiavi

• Con scope di progetto - Ogni chiave è legata a un progetto specifico e può accedere solo alle risorse di quel progetto.
• Denominate - Assegna nomi leggibili per una gestione facile.
• Revocabili - Le chiavi possono essere revocate istantaneamente. Le chiavi revocate smettono immediatamente di autenticarsi.
• Tracciate all’uso - Il timestamp lastUsedAt si aggiorna a ogni utilizzo, aiutando a identificare le chiavi obsolete.

Formato della risposta

Tutte le risposte dell’API usano un envelope JSON coerente:

Risposta di successo

{
  "data": {
    "id": "abc123",
    "name": "My Project",
    ...
  }
}

Risposta di errore

{
  "error": "Human-readable error message"
}

Codici di errore

• 400 Bad Request - Campi obbligatori mancanti, body JSON non valido o parametri di query non validi.
• 403 Forbidden - Chiave API non valida, chiave revocata, o la chiave non ha accesso al progetto richiesto.
• 404 Not Found - La risorsa richiesta non esiste o è stata eliminata in modo permanente.
• 500 Internal Server Error - Si è verificato un errore inatteso. Il messaggio di errore è incluso nel body della risposta.

Gestire le chiavi tramite l’API

L’API stessa fornisce endpoint per la gestione delle chiavi (hai bisogno di una chiave esistente per usarli):

• GET /api/v1/project/api-keys - Elenca tutte le chiavi del progetto (mostra prefisso, nome, date, stato).
• POST /api/v1/project/api-keys/generate - Genera una nuova chiave. Body: { "name": "Key Name" }. Restituisce la chiave completa (unica volta in cui viene mostrata).
• POST /api/v1/project/api-keys/revoke - Revoca una chiave. Body: { "keyId": "..." }.

Chiavi API dei provider

Separate dalle chiavi API di progetto, CodeCourier gestisce le chiavi dei provider per i servizi esterni usati al runtime della sandbox (E2B, Anthropic, OpenRouter, OpenAI, GitHub). Queste vengono configurate tramite gli endpoint /api/v1/project/provider-keys/*. Tutte le chiavi dei provider vengono cifrate prima della memorizzazione; solo gli ultimi quattro caratteri vengono memorizzati in chiaro per la visualizzazione.

Best practice di sicurezza

• Non committare mai le chiavi API nel controllo di versione. Usa variabili d’ambiente o un secrets manager.
• Ruota le chiavi regolarmente. Revoca e rigenera le chiavi periodicamente. Il campo lastUsedAt aiuta a identificare attività sospette.
• Usa nomi descrittivi.Denomina le chiavi in base al loro caso d’uso (ad es., «CI Pipeline», «Staging Agent») così sai quale revocare in caso di compromissione.
• Revoca le chiavi inutilizzate. Le chiavi che non sono state usate da mesi dovrebbero essere revocate.