Authentification et clés d’API

Chaque appel à /v1 porte une clé d’API dans l’en-tête Authorization, en HTTPS. Aucune autre forme (paramètre d’URL, cookie) n’est acceptée.

Authorization: Bearer vf_live_…

Deux types de clés

vf_test_… : bac à sable. Envois simulés, IA simulée, rien n’est facturé. Disponible dès la création du compte (3 clés actives au plus).
vf_live_… : production. Vrais courriers, débités du crédit prépayé. Disponible une fois la production ouverte (10 clés actives au plus).

Le préfixe fait foi : une clé test ne peut jamais poster un courrier. Chaque réponse porte l’en-tête X-Vitef-Env: test ou live.

Créer, faire tourner, révoquer

Tout se passe dans l’onglet « Clés d’API » de votre espace développeur. vitef ne conserve que l’empreinte chiffrée (SHA-256) de la clé : elle est affichée une seule fois, à sa création. Perdue, elle ne se récupère pas : créez-en une autre. Pour la faire tourner, créez la nouvelle clé, déployez-la, puis révoquez l’ancienne ; la révocation est immédiate.

Bonnes pratiques

Gardez la clé côté serveur, dans un gestionnaire de secrets ou une variable d’environnement. Jamais dans une application mobile, un navigateur ou un dépôt Git.
Une clé par application ou par environnement, nommée clairement : en cas de fuite, vous ne révoquez que celle-là.
La colonne « dernier appel » de l’espace développeur signale une clé inutilisée, à révoquer.

Erreurs d’authentification

Requête

curl "https://app.vitef.com/v1/catalogue" \
  -H "Authorization: Bearer $VITEF_API_KEY"

Réponse 401

{
  "error": {
    "code": "invalid_api_key",
    "message": "Votre clé d’API est invalide."
  }
}

invalid_api_key (401) : clé absente, mal formée ou inconnue.
revoked_api_key (401) : clé révoquée.
live_not_enabled (403) : clé live alors que la production n’est pas ouverte. account_suspended (403) : compte suspendu.

Étape suivante : environnements et bac à sable