Authentification
L'API CONVOY s'authentifie à l'aide de clés API secrètes. Chaque requête doit porter votre clé dans l'en-tête Authorization. Les requêtes sans clé valide renvoient une erreur 401.
Clés API
Créez vos clés dans l'espace entreprise, carte Clés API (5 clés actives au plus). La clé complète n'est affichée qu'une fois, à sa création : CONVOY n'en garde qu'une empreinte. Chaque environnement émet ses propres clés, reconnaissables à leur préfixe :
| Clé | Environnement | Usage |
|---|---|---|
cvk_live_… | Live | Déclenche de vraies livraisons, payées par la carte enregistrée. |
cvk_test_… | Test | Environnement de recette : paiements Stripe de test, aucun débit réel. |
En-tête d'autorisation
Transmettez votre clé en tant que jeton Bearer dans l'en-tête HTTP Authorization de chaque requête :
Authorization: Bearer cvk_live_•••Exemple de requête authentifiée récupérant une livraison :
curl https://convoyapp.fr/api/v1/deliveries/ord_3f9a1c27b84d6e05a2c1 \
-H "Authorization: Bearer cvk_live_•••"Rotation des clés
Vous pouvez créer une nouvelle clé à tout moment depuis l'espace entreprise. Une clé reste valide jusqu'à sa révocation : créez la nouvelle, déployez-la, puis révoquez l'ancienne, sans interruption de service. La révocation est immédiate.
| Étape | Action |
|---|---|
| 1 · Générer | Créez une nouvelle clé dans l'espace entreprise (carte Clés API). |
| 2 · Déployer | Mettez à jour la variable d'environnement de vos services. |
| 3 · Révoquer | Révoquez l'ancienne clé une fois le déploiement vérifié. |
Bonnes pratiques de sécurité
- Stockez les clés dans des variables d'environnement ou un gestionnaire de secrets, jamais en dur dans le code.
- Utilisez toujours HTTPS — les requêtes en HTTP clair sont refusées.
- Effectuez les appels exclusivement depuis votre back-end. N'intégrez jamais une clé secrète dans une application front-end.
- Appliquez le principe du moindre privilège : une clé distincte par service ou environnement.
- Surveillez l'activité et procédez à une rotation immédiate au moindre doute de compromission, puis révoquez la clé exposée.
Erreur d'authentification
Une clé manquante, révoquée ou invalide renvoie un statut 401 Unauthorized :
{
"error": {
"type": "authentication_error",
"code": "invalid_api_key",
"message": "Clé API invalide ou révoquée."
}
}