Authentification et clés API

Toutes les routes de l'API s'authentifient avec une clé API. La clé porte votre compte et ses permissions (scopes) ; vous n'avez jamais à préciser quel client vous êtes, et vous ne pouvez pas en désigner un autre.

Obtenir une clé

Vous créez vos clés vous-même dans l'application, dans Paramètres → Réglages → Clés API. Seuls le propriétaire du compte et ses administrateurs peuvent créer ou révoquer une clé ; les autres membres voient la liste. Réservé aux paliers payants : sur le plan Découverte, la création est refusée (plan_free_no_api).

1. Donnez un nom à la clé (par exemple « Looker Studio » ou « synchronisation entrepôt »), cochez les scopes dont l'intégration a besoin, et choisissez une expiration : jamais, 90 jours ou 1 an.
2. La clé s'affiche une seule fois. Seule son empreinte (SHA-256) est conservée : DURUM ne peut pas vous la remontrer. Conservez-la dans un gestionnaire de secrets.
3. Pour révoquer une clé, utilisez le bouton Révoquer de la même page. Une clé révoquée ou expirée répond 401 immédiatement.

Une clé ne voit que le compte sur lequel elle a été créée. Aucun paramètre de l'API ne permet de désigner un autre compte, et chaque réponse est vérifiée avant de sortir : une ligne qui n'appartiendrait pas à votre compte bloque la réponse entière (500 tenant_barrier).

Format de la clé

Une clé commence toujours par durum_sk_live_, suivi de 32 caractères aléatoires (alphabet base64url). Exemple de forme : durum_sk_live_Ab3dEf…. Les huit premiers caractères après le préfixe servent d'identifiant lisible (« préfixe ») dans les échanges avec votre gestionnaire de compte : ils permettent de désigner une clé sans jamais la retranscrire en entier.

Utiliser la clé

Passez la clé dans l'en-tête Authorization avec le schéma Bearer :

curl "https://app.durum.ai/api/v1/dashboard/kpis" \
  -H "Authorization: Bearer durum_sk_live_VOTRE_CLE"

L'en-tête x-api-key: durum_sk_live_VOTRE_CLE est également accepté. Si les deux sont présents, Authorization est lu en premier.

Ne jamais exposer la clé dans un navigateur

L'API accepte les requêtes de n'importe quelle origine (CORS ouvert) : la clé est la seule protection. Appelez l'API depuis un serveur, un script ou un outil BI, jamais depuis du code visible par vos visiteurs.

Scopes

Une clé n'atteint que les scopes qu'elle porte. Chaque route exige exactement un scope ; sans lui, la réponse est 403.

Scopes de lecture

Scope	Donne accès à
read:dashboard	KPI agrégés, série quotidienne, répartitions
read:ads	dépenses par annonce et par campagne, règles d'ads et historique d'exécution
read:attribution	attribution multi-touch, santé de capture, rapport d'attribution
read:events	événements CRM (leads, RDV, ventes, paiements, annulations) et leur résumé
read:sales	résumé commercial, performance par rep, cycle de vente
read:finance	P&L et revenus (marges retirées)
read:funnel	funnel et conversion
read:contacts	contacts, clients, achats
read:calls	appels d'un contact, liste des appels, transcription, enregistrement
read:journeys	parcours clients, parcours d'un contact, flux de points de contact
read:creatives	besoins créatifs en attente
read:icp	critères ICP
read:capi	pixels Meta connectés (sans les jetons)

Scopes d'écriture

Ils ne sont jamais accordés par défaut : demandez-les explicitement.

Scope	Permet de
write:goals	remplacer vos objectifs KPI
write:settings	définir votre règle de comptage des ventes
write:icp	définir vos critères ICP
write:ads	activer, désactiver, passer en simulation ou supprimer une règle d'ads
write:creatives	obtenir une autorisation de dépôt de visuel, déposer une créa en réserve, acquitter des besoins créatifs

Scope global

Le scope * accorde tous les scopes, lecture et écriture. Il n'est attribué que sur demande motivée.

Limite de débit

• 600 requêtes par minute et par clé, comptées par fenêtre fixe de 60 secondes.
• Chaque réponse porte les en-têtes X-RateLimit-Limit (600) et X-RateLimit-Remaining (requêtes restantes dans la fenêtre courante).
• Au-delà, la réponse est 429 avec retry_after_seconds: 60.
• Les échecs d'authentification sont aussi freinés par adresse IP : au-delà de 20 réponses 401 en une minute, la réponse est 429 avec too_many_failed_attempts pendant la fin de la minute.

Journal d'accès

Chaque requête authentifiée est journalisée par DURUM : identifiant de la clé, méthode, chemin, scope exigé, code de réponse, adresse IP et horodatage. La date de dernière utilisation de chaque clé est également mise à jour. Ce journal sert à l'audit de sécurité ; il n'est pas consultable via l'API.

Erreurs d'authentification et d'accès

Code	Corps JSON	Cause
401	{ "error": "invalid_or_missing_api_key" }	en-tête absent, clé au mauvais format, inconnue, révoquée ou expirée
403	{ "error": "insufficient_scope", "required": "read:calls" }	la clé ne porte pas le scope exigé (required indique lequel)
403	{ "error": "plan_free_no_api" }	l'espace de travail est sur le plan Découverte : l'API REST et le serveur MCP exigent un palier payant
403	{ "error": "forbidden" }	la ressource demandée (par exemple un appel) n'appartient pas à votre compte
429	{ "error": "rate_limited", "retry_after_seconds": 60 }	limite de débit dépassée
429	{ "error": "too_many_failed_attempts", "retry_after_seconds": 60 }	trop d'échecs d'authentification depuis votre adresse IP
500	{ "error": "tenant_barrier" }	la réponse a été bloquée par la vérification de compte ; contactez DURUM

Les autres codes (400, 404, 405, 502) sont décrits dans la référence de l'API.