Comptes, environnements et clés

Avant la première requête, trois questions se posent : quel compte, quelle offre, et quelle clé. Cette page y répond.

Ce qu'il faut pour appeler l'API

Il vous faut	Détail
Un compte Metaventus	Celui de votre entreprise, ou celui d'un client si vous intégrez pour lui
Un plan professionnel	La création de clés API n'est pas ouverte sur l'offre gratuite
Une clé secrète	Créée dans le Centre d'administration → Clés API, affichée une seule fois

Offre requise

Sur l'offre gratuite, l'API n'est pas ouverte : la création de clés demande un plan professionnel. Changez d'offre depuis Facturation → Abonnement, ou écrivez-nous si votre cas ne rentre pas dans les cases — un projet d'intégration se discute.

Test et production

Le préfixe d'une clé dit dans quel environnement elle agit, et il n'y a jamais d'ambiguïté à la lecture :

Préfixe	Environnement	Ce qu'elle touche
sk_live_…	Production	Vos données réelles, vos envois réels, votre facturation
sk_test_…	Hors production	Un environnement séparé, sans effet sur vos données réelles
pk_live_… / pk_test_…	Clé publique	Intégrations côté navigateur ; n'ouvre pas les endpoints de cette référence

Utilisez une clé par environnement, et jamais une clé de production dans un script de développement : c'est la seule règle qui évite d'écrire dans le CRM d'une entreprise en cherchant à tester une pagination.

Ce que voit une clé

Une clé agit dans le périmètre du compte qui l'a créée, et de l'espace de travail auquel elle est rattachée. Deux conséquences pratiques :

• une ressource appartenant à un autre compte répond 404, jamais 403 — la réponse est volontairement indistinguable de « n'existe pas », pour ne pas confirmer l'existence d'un identifiant qui ne vous appartient pas ;
• les données créées par l'API portent l'identité du créateur de la clé comme acteur, et atterrissent dans l'espace de travail de la clé.

Restreindre une clé

Trois verrous, cumulables, posés à la création ou plus tard :

• Portées (scopes) : les ressources qu'elle peut atteindre. Une clé qui ne fait que lire des contacts n'a rien à faire dans les factures.
• Adresses IP : la liste des adresses d'où elle est acceptée. C'est ce qui transforme une clé volée en clé inutile.
• Date d'expiration : au-delà, elle cesse d'authentifier.

Faire tourner une clé sans coupure

Créez la nouvelle clé, déployez-la, vérifiez qu'elle passe, puis révoquez l'ancienne. Dans cet ordre, aucune requête ne tombe. Une clé révoquée répond 401 immédiatement, et la révocation est définitive : on ne la réactive pas, on en crée une autre.

En cas de fuite

Révoquez d'abord, enquêtez ensuite. Une clé publiée dans un dépôt, un ticket ou une capture d'écran doit être considérée comme compromise, même si rien ne prouve qu'elle a servi.