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.

Droits de la clé (scopes)

Chaque clé porte des droits de la forme ressource:action. Une route n’accepte que les clés qui ont son droit ; sinon : 403 insufficient_scope, rien n’est exécuté ni débité. À la création, l’espace développeur propose « Tous les droits » (valeur par défaut), « Lecture seule » ou un choix case par case. Donnez à chaque intégration le minimum nécessaire : un tableau de bord qui suit vos envois n’a besoin que de mailings:read.

Droit	Routes
`catalogue:read`	Catalogue, rendu des lettres, calculs, estimations, recherche et partage de dépenses
`letters:write`	PDF des lettres
`mailings:read`	Suivi des envois et preuves
`mailings:write`	Envoi postal (facturé)
`data:read`	Entreprises, carburants, adresses, communes et itinéraires
`ai:write`	Outils IA (facturés)
`requests:read`	Suivi des demandes de service
`requests:write`	Demandes de service

Le droit de chaque route figure aussi dans la référence (exigence de sécurité de l’opération).

Réponse 403

{
  "error": {
    "code": "insufficient_scope",
    "message": "Cette clé d’API n’a pas le scope « mailings:write » nécessaire à cette route. Créez une clé avec ce scope dans votre espace développeur.",
    "details": {
      "required": "mailings:write",
      "granted": [
        "catalogue:read",
        "mailings:read",
        "data:read",
        "requests:read"
      ]
    }
  }
}

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

Appelez l’API depuis votre serveur. Gardez la clé dans un gestionnaire de secrets ou une variable d’environnement, jamais dans une application mobile, un navigateur ou un dépôt Git. L’API n’envoie aucun en-tête CORS : un appel depuis une page web est bloqué par le navigateur, à dessein.
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://api.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