Authentification

Chaque requête à l’API REST CodeCourier doit être authentifiée avec une clé API à scope de projet. Cette page explique comment créer des clés, comment les inclure dans les requêtes et comment gérer les erreurs d’authentification.

Créer une clé API

1. Ouvrez votre projet dans le dashboard CodeCourier.
2. Rendez-vous dans Project Settings et ouvrez la section API Keys.
3. Cliquez sur Generate New Keyet fournissez un nom descriptif (p. ex., «CI Pipeline» ou «LLM Agent»).
4. Le système affiche la clé complète exactement une fois. Copiez-la immédiatement et stockez-la en lieu sûr. CodeCourier ne stocke qu’un hash SHA-256 - la clé brute ne peut pas être récupérée.

Vous pouvez aussi créer des clés programmatiquement via la Project API : POST /api/v1/project/api-keys/generate.

Format de clé API

Toutes les clés API de projet suivent un format de préfixe reconnaissable :

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

Les clés sont préfixées par cc_live_ (production) ou cc_test_ (environnements de test). Le préfixe plus les 8 premiers caractères servent de préfixe d’affichage montré dans le dashboard. La clé complète est une longue chaîne aléatoire utilisée pour l’authentification.

Utiliser la clé API

Incluez la clé en tant que bearer token dans le header Authorization de chaque requête :

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

Pour les requêtes POST avec 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 de base

L’URL de base est l’endpoint HTTP Actions de votre déploiement Convex :

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

Erreur courante : Utilisez .convex.site - PAS .convex.cloud. Le domaine .convex.cloud est l’URL WebSocket de données Convex interne et ne servira pas les requêtes de l’API REST. Seul .convex.site expose les HTTP Actions.

Vous pouvez trouver le nom de votre déploiement dans le dashboard Convex (p. ex., happy-animal-123), ce qui donne une URL de base de https://happy-animal-123.convex.site/api/v1/.

Propriétés des clés

• À scope de projet - Chaque clé est liée à un projet spécifique et ne peut accéder qu’aux ressources de ce projet.
• Nommées - Assignez des noms lisibles pour une gestion facile.
• Révocables - Les clés peuvent être révoquées instantanément. Les clés révoquées cessent immédiatement de s’authentifier.
• Suivies à l’usage - L’horodatage lastUsedAt se met à jour à chaque utilisation, aidant à identifier les clés obsolètes.

Format de réponse

Toutes les réponses de l’API utilisent une enveloppe JSON cohérente :

Réponse de succès

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

Réponse d’erreur

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

Codes d’erreur

• 400 Bad Request - Champs requis manquants, body JSON invalide ou paramètres de query invalides.
• 403 Forbidden - Clé API invalide, clé révoquée, ou la clé n’a pas accès au projet demandé.
• 404 Not Found - La ressource demandée n’existe pas ou a été supprimée définitivement.
• 500 Internal Server Error - Une erreur inattendue s’est produite. Le message d’erreur est inclus dans le body de la réponse.

Gérer les clés via l’API

L’API elle-même fournit des endpoints pour la gestion des clés (vous avez besoin d’une clé existante pour les utiliser) :

• GET /api/v1/project/api-keys - Lister toutes les clés du projet (montre le préfixe, le nom, les dates, le statut).
• POST /api/v1/project/api-keys/generate - Générer une nouvelle clé. Body : { "name": "Key Name" }. Renvoie la clé complète (seule fois où elle est montrée).
• POST /api/v1/project/api-keys/revoke - Révoquer une clé. Body : { "keyId": "..." }.

Clés API des providers

Distinctes des clés API de projet, CodeCourier gère les clés des providers pour les services externes utilisés au runtime de la sandbox (E2B, Anthropic, OpenRouter, OpenAI, GitHub). Elles sont configurées via les endpoints /api/v1/project/provider-keys/*. Toutes les clés des providers sont chiffrées avant le stockage ; seuls les quatre derniers caractères sont stockés en clair pour l’affichage.

Bonnes pratiques de sécurité

• Ne committez jamais de clés API dans le contrôle de source. Utilisez des variables d’environnement ou un secrets manager.
• Faites tourner les clés régulièrement. Révoquez et régénérez les clés périodiquement. Le champ lastUsedAt aide à identifier les activités suspectes.
• Utilisez des noms descriptifs.Nommez les clés d’après leur cas d’usage (p. ex., «CI Pipeline», «Staging Agent») pour savoir laquelle révoquer en cas de compromission.
• Révoquez les clés inutilisées. Les clés qui n’ont pas été utilisées depuis des mois devraient être révoquées.