Authentification API et gestion des clés pour ElevenAPI

L’authentification API permet à un service de vérifier qu’une requête entrante est autorisée à agir sur un compte. Par exemple, avec ElevenAPI, les identifiants API autorisent les requêtes qui consomment des crédits, génèrent de la voix ou de la musique à grande échelle, et, dans certains cas, accèdent à de l’audio sensible.

Une clé divulguée coûte de l’argent et peut être utilisée pour générer du contenu sous votre compte. Elle peut aussi donner un accès trop large à vos plateformes, ce qui peut entraîner des fuites de données ou d’autres risques. Déjà en 2020, plus de 90 % des développeurs utilisaient des API dans au moins un processus quotidien. Aujourd’hui, avec la montée des protocoles de contexte de modèle (MCP) et de l’IA, les API sont partout.

Cet article explique comment bien authentifier les API et gérer les clés tout au long de leur cycle de vie : définition du périmètre, rotation, contrôles organisationnels, audit et gestion des incidents. Il vous aidera à mettre en place une authentification et une gestion des clés API efficaces dans votre équipe. Pour référence pendant votre lecture, gardez le guide d’authentification et la documentation sur les tokens à usage unique ouverts.

À retenir

• ElevenAPI authentifie chaque requête via un secret unique, l’en-tête xi-api-key. Toute personne possédant une clé peut donc dépenser des crédits et générer de l’audio sous le compte.
• Ne mettez jamais une clé API à longue durée de vie dans un navigateur, une application mobile ou tout autre support accessible à l’utilisateur. Gardez-les sur un serveur que vous contrôlez.
• Pour les usages côté client, il faut utiliser des tokens à usage unique et courte durée générés côté serveur, jamais la clé longue durée.
• Vous pouvez limiter l’impact d’une fuite en limitant les droits des clés, en séparant les clés par environnement et en les faisant tourner régulièrement.
• L’audit et la détection d’anomalies aident à prévenir les fuites de clés et les mauvaises surprises.

Qu’est-ce que l’authentification API ?

L’authentification API permet à un service de vérifier qu’une requête entrante est autorisée à agir sur un compte avant de traiter la demande. Le demandeur présente un identifiant, le service le vérifie, puis répond si tout est correct.

En résumé, cela répond à la question : cette requête est-elle autorisée à agir pour ce compte ? Il est important de noter que ce processus est différent de l’autorisation API, qui définit ce qu’une requête authentifiée peut faire dans votre système.

Qu’est-ce que la gestion des clés ?

La gestion des clés regroupe toutes les pratiques permettant de gérer une clé API tout au long de son cycle de vie. Cela inclut la création, le stockage, l’utilisation, la rotation et la révocation des accès. Ces systèmes sont là pour garantir la sécurité d’une clé API de bout en bout.

Avec une gestion rigoureuse des clés, vous pouvez éviter les fuites et réduire le risque qu’elles deviennent publiques.

Pourquoi la sécurité des clés API est importante : le modèle de menace

Maintenant que l’authentification et la gestion des clés sont définies, il est utile de préciser ce qui peut mal tourner si une clé est mal gérée. Comprendre le modèle de menace permet de donner un sens à chaque bonne pratique : chacune vise à réduire soit la probabilité d’une fuite, soit son impact.

ElevenAPI s’authentifie via un seul mécanisme : l’en-tête xi-api-key. Toute personne possédant la clé est autorisée, il n’y a pas de second facteur sur la requête.

Avec votre clé, quelqu’un peut dépenser vos crédits. Text to Speech, Speech to Text, musique et effets sonores sont tous comptabilisés, et un attaquant avec une clé valide peut générer en continu jusqu’à épuisement de votre quota ou solde.

Il peut générer à grande échelle, et notre modèle de limitation de débit rend la situation plus sérieuse qu’il n’y paraît. La limite dépend de la concurrence, pas simplement du nombre de requêtes par minute. Une clé avec une limite de concurrence de cinq pour une famille de modèles peut permettre de nombreuses générations simultanées, et un attaquant qui comprend ces limites pourra en abuser en parallèle.

Il peut produire du contenu sous votre compte. Tout audio généré avec votre clé est attribué à votre espace de travail, et selon les voix et entrées utilisées, cela peut poser des problèmes de réputation, voire parfois juridiques.

Les façons dont les clés s’échappent sont banales, et ce sont les mêmes causes que pour toutes les autres fuites d’identifiants :

• Clés API dans le code côté client : Une clé incluse dans un bundle navigateur, un binaire mobile ou une application monopage est, en pratique, publique. La minification n’est pas une protection.
• Clés API dans les dépôts : Clés en dur dans le code commit sur Git, y compris dans des dépôts privés qui deviennent publics ou sont largement clonés, et dans des fichiers comme .env qui n’auraient jamais dû être suivis.
• Clés API dans les logs et traces : Les outils de logs, de suivi d’erreurs et d’observabilité capturent souvent les en-têtes HTTP. Une clé dans xi-api-key se retrouve dans vos logs, chez votre fournisseur APM, et accessible à toute personne ayant accès à ces données.
• Clés API dans l’intégration continue et les captures d’écran : Logs de build, tickets de support, terminaux partagés.

Chaque section ci-dessous vise à réduire la probabilité ou l’impact de l’un de ces scénarios.

La règle d’or : gardez les clés API côté serveur

Tout le reste dans cet article vise à réduire les risques liés à l’authentification et à la gestion des clés API. Cette règle est la base de tout et doit être appliquée en priorité.

Comme le mécanisme est très simple, la règle d’or est qu’une clé API à longue durée de vie doit rester uniquement sur un serveur que vous contrôlez. Elle ne doit jamais être incluse dans un navigateur, une application mobile, un client desktop ou tout fichier téléchargeable et inspectable par un utilisateur. Si la clé est dans le code côté client, considérez-la comme déjà compromise.

Le SDK lit automatiquement ELEVENLABS_API_KEY, donc le code le plus propre ne passe rien et initialise simplement le client une fois.

import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

// Reads process.env.ELEVENLABS_API_KEY when apiKey is omitted - never a literal.
const elevenlabs = new ElevenLabsClient();

const audio = await elevenlabs.textToSpeech.convert("JBFqnCBsd6RMkjVDRZzb", {
  text: "Generated entirely server-side.",
  modelId: "eleven_flash_v2_5",
  outputFormat: "mp3_44100_128",
});

En production, la clé doit être récupérée depuis un gestionnaire de secrets (AWS Secrets Manager, GCP Secret Manager, HashiCorp Vault ou l’équivalent de votre plateforme) au démarrage du processus, et non intégrée dans une image ou un .env commité dans le dépôt.

Tokens à usage unique pour les applications côté client

La règle d’or est absolue, mais de nombreux cas d’usage légitimes nécessitent que le client accède lui-même à ElevenAPI : un navigateur qui lit du Text to Speech en streaming, une application mobile qui enregistre de l’audio à transcrire, ou un agent en temps réel dans l’onglet de l’utilisateur. La clé longue durée ne doit jamais y être. La solution est de donner au client un identifiant à faible risque en cas de fuite : un token à usage unique et courte durée.

Votre serveur détient la clé longue durée, authentifie et autorise l’utilisateur avec votre propre logique de session, puis génère un token à usage unique et ne transmet que celui-ci au client. Le token expire rapidement et est limité à l’opération pour laquelle il a été émis, donc une fuite a peu d’impact. Consultez la documentation sur les tokens à usage unique pour les endpoints supportés et le format exact de la requête.

Voici la logique essentielle d’un endpoint de courtier. Il autorise l’utilisateur avec votre logique de session, puis génère un token via l’endpoint documenté. La requête part avec la clé longue durée xi-api-key depuis le serveur, et seul le token à usage unique est renvoyé au client.

// ... express app and route boilerplate
app.post("/api/voice-token", async (req, res) => {
  // 1. Authorize the user with YOUR session/auth system first.
  if (!req.session?.user) return res.status(401).json({ error: "unauthorized" });

  // 2. Mint a short-lived token server-side. The long-lived key travels only
  //    in this server-to-server request, never to the browser.
  const response = await fetch("https://api.elevenlabs.io/v1/tokens", {
    method: "POST",
    headers: {
      "xi-api-key": process.env.ELEVENLABS_API_KEY as string,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({}), // populate per the tokens reference
  });

  // 3. Return only the short-lived token. The API key never leaves the server.
  res.json({ token: await response.json() });
});

Le navigateur utilise ensuite ce token pour se connecter, et la clé longue durée n’entre jamais dans la page.

Limiter les droits des clés au strict nécessaire

Le principe du moindre privilège veut que chaque clé n’ait que les permissions nécessaires à sa tâche, et rien de plus. ElevenAPI vous permet de mettre en place plusieurs restrictions basées sur les permissions pour limiter ce qu’une clé peut ou ne peut pas faire.

Une clé toute-puissante est le pire scénario en cas de fuite, et c’est aussi le choix par défaut le plus simple. Il vaut mieux partir du principe qu’une clé finira par fuiter, et s’assurer que, si cela arrive, elle ne pourra faire que ce qui est strictement nécessaire.

Commencez par restreindre le périmètre, ce qui limite les endpoints API qu’une clé peut appeler. Une clé utilisée uniquement pour la transcription n’a pas besoin d’accès à Text to Speech ; une clé pour une fonctionnalité musicale n’a pas besoin d’accéder à la gestion des voix.

Ensuite, limitez le quota de crédits. Attribuer une limite de crédits personnalisée par clé limite l’impact financier d’une fuite et permet aussi de contenir les boucles infinies dans votre propre code.

Le filtrage par IP va plus loin. Vous pouvez restreindre une clé à certaines adresses IP ou plages CIDR, et les requêtes venant d’IP non autorisées sont rejetées avec un code 403. Cette fonctionnalité Entreprise est actuellement en préversion, disponible via votre gestionnaire de compte.

Enfin, ne partagez pas une clé entre développement, préproduction et production. Générez une clé distincte par environnement, chacune avec son propre périmètre et quota. Cela évite qu’une fuite sur un ordinateur de développeur n’impacte la production, permet de faire tourner une clé sans perturber les autres environnements, et rend les logs plus lisibles car le trafic est déjà segmenté par origine.

Rotation des clés API

La rotation des clés consiste à remplacer régulièrement une clé par une nouvelle. C’est aussi ce qu’il faut faire en cas de suspicion de fuite ou d’exposition.

En programmant la rotation, vous réduisez la fenêtre pendant laquelle une fuite non détectée peut être exploitée. La rotation n’est facile que si votre code est prévu pour, donc pensez-y dès le départ.

La technique de base consiste à faire coexister deux clés, ce qui permet une transition sans interruption :

1. Générez une nouvelle clé API : Ajoutez une nouvelle clé à côté de l’ancienne, avec le même périmètre, quota et restrictions IP. Les deux sont valides.
2. Mettez à jour la clé : Déployez la nouvelle clé en mettant à jour le secret dans votre gestionnaire de secrets et laissez les instances la récupérer (redémarrage, relecture ou rafraîchissement du gestionnaire de secrets selon votre configuration).
3. Vérifiez le trafic : Assurez-vous que le trafic passe bien par la nouvelle clé. Surveillez l’utilisation pour vérifier que l’ancienne clé n’est plus utilisée.
4. Retirez l’accès à l’ancienne clé : Révoquez l’ancienne clé dès qu’elle n’a plus de trafic pendant une période de sécurité.

Comme les deux clés sont valides pendant la transition, il n’y a jamais de moment où les requêtes échouent faute d’identifiant. Cette période de recouvrement a un autre avantage : une instance mal configurée se révèle en continuant d’utiliser l’ancienne clé, ce qui permet de la corriger avant de couper l’accès.

Pour que la rotation soit transparente, structurez votre code pour que la rotation soit un changement de configuration, jamais un changement de code. Lisez la clé à un seul endroit, là où elle peut être rafraîchie, et laissez un seul paramètre décider du secret actif.

// Rotation is driven by configuration, not code edits. The secret manager (or
// the deploy that injects env vars) is the single point of change.
// ELEVENLABS_KEY_ACTIVE selects which slot is live, enabling overlap.
let client: ElevenLabsClient | undefined;

function activeKey(): string {
  const slot = process.env.ELEVENLABS_KEY_ACTIVE ?? "primary";
  const name = slot === "primary" ? "ELEVENLABS_API_KEY_PRIMARY" : "ELEVENLABS_API_KEY_SECONDARY";
  return process.env[name] as string;
}

function getClient(): ElevenLabsClient {
  return (client ??= new ElevenLabsClient({ apiKey: activeKey() }));
}

// Call after a secret refresh to pick up the rotated key without a deploy.
function resetClient(): void {
  client = undefined;
}

Pendant la transition, gardez PRIMARY et SECONDARY renseignés et basculez ELEVENLABS_KEY_ACTIVE. Le code de l’application ne change jamais.

En termes de fréquence, une rotation tous les 90 jours est un bon point de départ pour les clés backend, plus souvent pour les clés sensibles ou très utilisées, et immédiatement en cas d’exposition. Cela peut être automatisé avec une tâche planifiée qui génère, déploie, vérifie et révoque, transformant la rotation en tâche de fond.

Contrôles d’accès et permissions de l’espace de travail

Si la limitation du périmètre et la rotation sécurisent chaque clé, les contrôles d’espace de travail déterminent qui peut en créer. C’est l’occasion de définir et d’appliquer une politique organisationnelle, qui influencera toutes vos pratiques de gestion des clés à l’avenir.

Commencez par séparer les identifiants humains et machines. Les personnes se connectent au tableau de bord avec leur propre compte et permissions ; les services s’authentifient avec des clés ou, mieux, des comptes de service. N’utilisez pas une clé générée depuis l’accès personnel d’un individu pour un service, et ne partagez pas une clé machine entre plusieurs personnes. Cela facilite la révocation ciblée lors d’un départ ou de la mise hors service d’un service.

Les comptes de service servent le même objectif. Ils donnent une identité machine distincte de celle d’un humain, avec leur propre périmètre, ce qui rend l’audit plus fiable.

Ensuite, attribuez les accès par rôles plutôt qu’individuellement. Les espaces de travail permettent de gérer les permissions par groupe et par membre. Accordez le minimum de droits nécessaires à chaque groupe, révisez régulièrement les membres, et visez une organisation où aucun identifiant, humain ou machine, ne peut faire plus que ce que son rôle exige.

Audit et détection

Les étapes précédentes expliquent comment limiter l’impact d’une fuite. Ici, nous voyons comment détecter si une fuite a eu lieu. Une bonne détection repose sur trois habitudes.

La première est d’enregistrer quelle clé (par identifiant, jamais la valeur secrète) a servi quelle classe de requête, depuis où, et à quel volume. Supprimez l’en-tête xi-api-key de tous les logs et traces. Une règle de masquage dans votre middleware HTTP et dans la configuration APM élimine la cause la plus fréquente de fuite de clés dans les logs.

La deuxième est de surveiller la consommation de crédits pour détecter les anomalies. Suivez la consommation par clé dans le temps et alertez en cas d’écart : pic soudain, génération à des heures inhabituelles, ou une clé censée être inactive qui devient active.

La troisième est de surveiller les en-têtes de concurrence. Nous renvoyons le nombre actuel et maximal de requêtes simultanées dans les en-têtes current-concurrent-requests et maximum-concurrent-requests. Ils indiquent votre marge, et un maintien prolongé au maximum sans action de votre part est un signal fort d’abus. Utiliser l’endpoint HTTP brut expose directement ces en-têtes :

const resp = await fetch("https://api.elevenlabs.io/v1/text-to-speech/JBFqnCBsd6RMkjVDRZzb", {
  method: "POST",
  headers: {
    "xi-api-key": process.env.ELEVENLABS_API_KEY as string,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ text: "Monitoring headroom.", model_id: "eleven_flash_v2_5" }),
});

const current = resp.headers.get("current-concurrent-requests");
const maximum = resp.headers.get("maximum-concurrent-requests");
// Emit these to your metrics pipeline; alert on sustained saturation you did not cause.

Cela doit déclencher des alertes. Un tableau de bord non surveillé ne sert à rien. Intégrez les alertes de pic de crédits et de saturation de concurrence dans le même circuit d’alerte que pour les incidents, avec un responsable clair.

Gestion des incidents

Même avec les meilleurs systèmes de sécurité et de surveillance, il faut partir du principe qu’une clé finira par fuiter. Prévoir une liste d’actions pour limiter les dégâts vous donne une feuille de route qui fait gagner du temps et réduit l’impact.

Voici un plan d’action prédéfini en cas de fuite de clé API :

1. Révoquez immédiatement la clé compromise : N’attendez pas de comprendre toute l’ampleur du problème. Une clé révoquée ne peut plus générer, et la révocation est réversible car vous pouvez toujours en créer une nouvelle. C’est l’action la plus importante.
2. Faites tourner la clé : Si la clé compromise servait du trafic en production, utilisez la procédure de transition à l’envers : créez une nouvelle clé, basculez le trafic, puis vérifiez que la clé compromise n’est plus utilisée. Comme votre code lit la clé depuis la configuration, il suffit de changer la config, pas le code.
3. Évaluez l’impact via les logs d’utilisation : Une fois la fuite contenue, mesurez-la. Combien de temps la clé a-t-elle été exposée ? Quels crédits ont été consommés pendant cette période, et le schéma correspond-il à un usage légitime ou à un abus ? Quels endpoints ont été touchés ?
4. Faites tourner les secrets dépendants : Une clé ne fuite jamais seule. Si elle a été exposée dans un dépôt, un log ou une CI, considérez que les secrets voisins sont aussi exposés et faites-les tourner.
5. Corrigez la cause de la fuite : Trouvez comment la clé s’est échappée et corrigez le problème, sinon cela se reproduira : ajoutez le fichier à .gitignore et purgez l’historique, ajoutez le masquage d’en-tête au logger, sortez le secret de l’artifact de build, et limitez l’accès à la CI.
6. Rédigez un post-mortem : Documentez la chronologie, l’impact, la cause racine et les mesures concrètes prises (restriction du périmètre, filtrage IP, scanner de secrets en CI, rotation plus fréquente).

En suivant ces étapes, vous aurez un processus prêt à l’emploi en cas de fuite de clé API.

Conformité : SOC 2, HIPAA et conservation des données

L’authentification n’est qu’un aspect d’une évaluation de conformité plus large, et il est important de bien distinguer ce qui peut ou non être affirmé ici. Considérez ce qui suit comme des points de départ factuels, pas comme une validation pour votre cas.

ElevenLabs est conforme SOC 2. Pour les offres et usages éligibles, la conformité HIPAA et les modes sans conservation sont disponibles. Le mode sans conservation signifie que le contenu des requêtes n’est pas stocké après traitement, ce qui est important si vos entrées ou l’audio généré sont sensibles.

L’applicabilité d’un mode dépend de votre offre, de votre configuration et de ce que vous traitez. Vérifiez l’éligibilité et les conditions exactes pour votre compte avant de vous y fier, et combinez-les avec les contrôles d’accès décrits plus haut. Les certifications de conformité régissent la gestion de vos données par la plateforme ; la gestion des clés détermine qui peut agir en votre nom, et cette partie vous appartient.

À quoi ressemble une bonne sécurité des clés API

Des clés uniquement côté serveur éliminent la principale surface de fuite. Les tokens à usage unique étendent cette garantie aux clients qui doivent vraiment accéder à notre API. La limitation du périmètre et la séparation par environnement limitent l’impact d’une fuite. Une rotation intégrée à la configuration rend la récupération simple et sans risque. Les contrôles d’espace de travail distinguent bien les identités humaines et machines. L’audit transforme un abus en alerte plutôt qu’en mauvaise surprise sur la facture. Un guide écrit transforme un incident en procédure.

C’est la même hygiène des identifiants qui protège tout secret de valeur, appliquée à une clé dont la particularité est de dépenser de l’argent et de générer de l’audio à grande échelle.

Quand vous serez prêt à mettre cela en place pour vos requêtes réelles, le guide d’authentification et la documentation sur les tokens à usage unique listent les endpoints supportés. Pour comprendre le modèle de concurrence à surveiller, consultez la documentation sur les modèles et le guide de démarrage rapide de l’API.

Sécurisez votre intégration ElevenAPI

Une authentification API solide est un contrôle fondamental sur lequel reposent de nombreuses autres pratiques de sécurité. Utiliser uniquement des clés côté serveur, déployer des tokens à usage unique pour les clients, limiter les droits au strict nécessaire et intégrer la rotation dans la gestion des clés permet de réduire les risques à grande échelle.

Pour plus d’informations sur les endpoints supportés et le format exact des en-têtes à utiliser, consultez la documentation ElevenAPI. Si vous êtes prêt à commencer, demandez une clé API auprès de ElevenLabs pour commencer à créer dès aujourd’hui.

FAQ sur l’authentification API et la gestion des clés