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 facturés à l’usage, génèrent de la parole et de la musique à grande échelle et, dans certains déploiements, accèdent à des données audio sensibles. 

Une clé divulguée coûte de l’argent et peut servir à générer du contenu sous votre compte. Elle peut aussi donner un accès excessif à vos plateformes, créant des risques de fuites de données et d’autres vecteurs d’attaque. Dès 2020, plus de 90 % des développeurs utilisaient des API dans au moins un processus quotidien. Aujourd’hui, avec l’essor des protocoles de contexte de modèle (MCP) et de l’IA, les API sont partout.

Cet article explique comment authentifier correctement les API et gérer les clés tout au long de leur cycle de vie : périmètre d’accès, rotation, contrôles organisationnels, audit et réponse aux incidents. Il vous aidera à mettre en place une authentification API et une gestion des clés adaptées au sein de votre équipe. Pendant votre lecture, gardez ouverte la référence sur l’authentification et la référence sur les jetons à usage unique.

En résumé

• ElevenAPI authentifie chaque requête à l’aide d’un secret unique, l’en-tête xi-api-key. Toute personne détenant une clé peut donc dépenser des crédits et générer de l’audio sous le compte concerné.
• N’intégrez jamais une clé API longue durée dans un navigateur, une application mobile ou tout autre artefact qu’un utilisateur pourrait examiner. Conservez-la sur un serveur que vous contrôlez.
• Les cas d’usage côté client doivent s’authentifier avec des jetons à usage unique et de courte durée, émis côté serveur, et jamais avec la clé longue durée.
• Réduisez l’impact d’une fuite en limitant les clés au moindre privilège, en séparant les clés par environnement et en les renouvelant selon un calendrier défini.
• L’audit et la détection des anomalies contribuent à 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 confirmer qu’une requête entrante est autorisée à agir sur un compte précis avant de commencer son traitement. Le demandeur présente un identifiant, le service le vérifie, puis fournit une réponse après validation. 

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

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

La gestion des clés désigne l’ensemble des pratiques permettant de gouverner une clé API tout au long de son cycle de vie. Elle définit comment créer, stocker, utiliser, renouveler et révoquer l’accès aux clés. Ces systèmes assurent la sécurité d’une clé API de bout en bout. 

Des systèmes de gestion des clés rigoureux permettent d’éviter les fuites de clés et de réduire le risque qu’elles deviennent accessibles publiquement. 

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

Maintenant que l’authentification et la gestion des clés sont définies, il convient de préciser ce qui se produit lorsqu’une clé est mal gérée. Examiner d’abord le modèle de menace donne un objectif clair à chaque pratique présentée ensuite : chacune réduit soit le risque de fuite d’une clé, soit les dommages qu’elle occasionne en cas de fuite.

ElevenAPI s’authentifie par un mécanisme unique reposant sur un secret : l’en-tête xi-api-key. Toute personne qui détient la clé est autorisée, sans second facteur dans la requête elle-même.

Avec votre clé, une personne malveillante peut dépenser vos crédits. Text to Speech, Speech to Text, la musique et les effets sonores sont tous facturés à l’usage ; un attaquant muni d’une clé valide peut générer du contenu en continu jusqu’à épuisement de votre quota ou de votre solde.

Ils peuvent générer du contenu à grande échelle, et notre modèle de limitation du débit rend cette situation plus grave qu’il n’y paraît. La limite repose sur les requêtes simultanées, et non sur un simple quota de requêtes par minute. Une clé associée à une offre limitant à cinq les requêtes simultanées pour une famille de modèles donnée peut prendre en charge un nombre significatif de générations simultanées ; un attaquant qui comprend ces limites parallélisera l’abus.

Ils peuvent produire du contenu sous votre compte. Tout audio généré avec votre clé est attribué à votre Workspace et, selon les voix et les entrées utilisées, cela peut poser un risque pour votre réputation et, parfois, sur le plan juridique.

Les fuites de clés ont des causes ordinaires, identiques aux modes de défaillance qui divulguent tout autre type d’identifiant :

• Clés API dans le code côté client : une clé intégrée à un bundle de navigateur, un binaire mobile ou une application monopage est, en pratique, publique. La minification n’est pas de l’obfuscation.
• Clés API dans les dépôts : clés codées en dur et validées dans Git, y compris dans des dépôts privés qui deviennent ensuite publics ou sont largement clonés, ainsi que dans des fichiers tels que .env qui n’auraient jamais dû être suivis.
• Clés API dans les journaux et les traces : les enregistreurs de requêtes, outils de suivi des erreurs et pipelines d’observabilité capturent couramment les en-têtes HTTP. Une clé dans xi-api-key se retrouve dans votre stockage de journaux, chez votre fournisseur APM et auprès de toute personne ayant un accès en lecture à l’un ou l’autre.
• Clés API dans l’intégration continue et les captures d’écran : journaux de build, tickets d’assistance et terminaux partagés.

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

La règle fondamentale : conserver les clés API côté serveur

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

Le mécanisme étant si simple, la règle fondamentale est qu’une clé API longue durée ne doit se trouver que sur un serveur que vous contrôlez. Elle ne doit jamais être intégrée à un navigateur, une application mobile, un client de bureau ou tout artefact qu’un utilisateur peut télécharger et examiner. Si la clé se trouve dans du code côté client, considérez-la comme déjà compromise.

Le SDK lit automatiquement ELEVENLABS_API_KEY. Le code le plus propre ne transmet donc rien et initialise le client une seule 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, elle doit être chargée depuis un gestionnaire de secrets au démarrage du processus, et non intégrée à une image ou à un fichier .env validé dans le dépôt.

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

La règle fondamentale est absolue, mais de nombreux cas d’usage légitimes exigent que le client accède lui-même à ElevenAPI : un navigateur qui lit du Text to Speech en streaming, une application mobile qui capture de l’audio à transcrire ou un agent en temps réel exécuté dans l’onglet de l’utilisateur. La clé longue durée ne peut pas s’y trouver. La solution consiste à donner au client un identifiant à faible risque en cas de fuite : un jeton à usage unique et de courte durée.

Votre serveur conserve la clé longue durée, authentifie et autorise l’utilisateur selon votre propre logique de session, puis émet un jeton de courte durée qu’il transmet seul au client. Le jeton expire rapidement et est limité à l’opération pour laquelle il a été émis : s’il fuit, sa valeur est faible et disparaît vite. Consultez la référence des jetons à usage unique pour connaître les endpoints pris en charge et le format exact des requêtes.

Voici la logique essentielle d’un endpoint intermédiaire. Il autorise l’utilisateur avec votre propre logique de session, puis émet un jeton auprès de l’endpoint de jetons documenté. La requête est envoyée depuis le serveur avec la clé xi-api-key longue durée, et seul le jeton de courte durée obtenu 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 jeton pour se connecter, et la clé longue durée n’entre jamais dans la page.

Limiter les clés au moindre privilège

Le moindre privilège est le principe selon lequel chaque clé ne doit disposer que des autorisations nécessaires à sa tâche, et de rien d’autre. ElevenAPI vous permet de mettre en place plusieurs restrictions fondées sur les autorisations, qui encadrent ce qu’une clé peut ou ne peut pas faire.

Une clé unique toute-puissante est le pire scénario en matière d’impact, mais aussi le choix par défaut le plus simple. Il vaut mieux supposer que toute clé finira par fuiter et veiller à ce qu’elle ne puisse alors faire que ce qui est nécessaire à sa tâche.

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

Vient ensuite le quota de crédits. Définir une limite de crédits personnalisée par clé plafonne le préjudice financier d’une fuite et limite aussi les boucles incontrôlées dans votre propre code.

La liste blanche d’adresses IP va plus loin. Vous pouvez restreindre une clé à des adresses IP ou plages CIDR précises ; les requêtes provenant d’adresses IP non autorisées sont rejetées avec un code 403. Cette fonctionnalité Enterprise est actuellement disponible en préversion via votre responsable de compte.

Enfin, ne partagez pas une même clé entre les environnements de développement, de préproduction et de production. Émettez une clé distincte par environnement, avec son propre périmètre et quota. Les clés par environnement empêchent qu’une fuite sur l’ordinateur portable d’un développeur n’affecte les crédits de production, permettent de renouveler un environnement sans perturber les autres et facilitent l’interprétation des journaux d’utilisation, 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 une mesure à prendre dès que vous suspectez une compromission ou une exposition.

Planifiée, la rotation réduit aussi la période pendant laquelle une fuite non détectée peut être exploitée. Elle n’est simple que si votre code a été conçu en conséquence : prévoyez-la avant d’en avoir besoin.

La technique essentielle consiste à faire chevaucher les clés, afin d’assurer une bascule sans interruption :

1. Générer une nouvelle clé API : créez une nouvelle clé en parallèle de celle existante, avec le même périmètre, quota et restrictions IP. Les deux sont alors valides.
2. Mettre à jour la clé : déployez la nouvelle clé en mettant à jour le secret dans votre gestionnaire de secrets et en laissant les instances le récupérer (après un redémarrage, une nouvelle lecture ou une actualisation du gestionnaire de secrets, selon votre configuration).
3. Confirmer le trafic : vérifiez que le trafic passe par la nouvelle clé. Surveillez l’utilisation pour confirmer que l’ancienne clé n’est plus utilisée.
4. Supprimer l’accès de la clé : révoquez l’ancienne clé lorsqu’elle n’affiche plus aucun trafic pendant une période de sécurité suffisante.

Les deux clés étant valides pendant le chevauchement, les requêtes ne peuvent jamais échouer faute d’identifiant. Cette période présente un autre avantage : une instance mal configurée se révèle en continuant d’utiliser l’ancienne clé, ce qui vous permet de l’identifier avant de révoquer cette clé.

Pour que le chevauchement se déroule sans incident, structurez votre code de sorte que la rotation soit un changement de configuration, jamais une modification du code. Lisez la clé depuis un emplacement unique, où elle peut être actualisée, et laissez un seul commutateur déterminer quel secret est 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 un chevauchement, conservez PRIMARY et SECONDARY renseignés, puis basculez ELEVENLABS_KEY_ACTIVE. Le code de l’application ne change jamais.

Pour le rythme de rotation, un renouvellement tous les 90 jours est un bon paramètre par défaut pour les clés backend ; renouvelez plus souvent les clés à forte valeur ou largement accessibles, et immédiatement après toute exposition. Vous pouvez automatiser cette opération avec une tâche planifiée qui crée, déploie, vérifie et révoque les clés, transformant la rotation d’un événement en processus d’arrière-plan.

Contrôles d’accès et autorisations du Workspace

Si le périmètre et la rotation protègent les clés individuelles, les contrôles du Workspace déterminent qui peut les émettre au départ. Ils permettent de définir et d’appliquer une politique organisationnelle qui guidera toutes vos pratiques de gestion des clés.

Commencez par séparer les identifiants humains de ceux des machines. Les personnes se connectent au Dashboard avec leurs propres comptes et autorisations ; les services s’authentifient avec des clés ou, idéalement, des comptes de service. Ne laissez pas un service s’exécuter avec une clé émise depuis l’accès personnel d’un individu, et ne laissez pas plusieurs personnes partager une même clé machine. Cela facilite le départ d’un collaborateur ou le retrait d’un service : vous pourrez révoquer exactement le bon identifiant, sans dommages collatéraux.

Les comptes de service remplissent le même objectif. Ils donnent aux charges de travail machine une identité non liée à une personne, avec leur propre périmètre d’accès, ce qui garantit la fiabilité de votre piste d’audit.

Associez ensuite les accès à des rôles plutôt qu’à des personnes, une par une. Les Workspaces prennent précisément en charge les autorisations de groupes et de membres. Accordez le moindre privilège permettant à chaque groupe d’effectuer son travail, révisez régulièrement les membres et visez une organisation dans laquelle 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 réduire les dommages causés par une fuite. Cette étape détaille comment détecter une fuite lorsqu’elle survient. Une bonne détection repose sur trois habitudes. 

La première consiste à enregistrer quelle clé — par son identifiant, jamais par sa valeur secrète — a traité quel type de requête, depuis quelle origine et à quel volume. Supprimez l’en-tête xi-api-key de chaque couche de journalisation et de traçage. Une règle de masquage dans votre middleware HTTP et votre configuration APM élimine la principale cause de présence des clés dans les stockages de journaux.

La deuxième consiste à surveiller les anomalies de consommation de crédits. Suivez la consommation de crédits par clé au fil du temps et déclenchez des alertes en cas d’écart par rapport au niveau habituel : pic soudain, génération à des heures inhabituelles ou activation soudaine d’une clé censée être inactive.

La troisième consiste à surveiller les en-têtes de requêtes simultanées. Nous renvoyons le nombre actuel et maximal de requêtes simultanées dans chaque réponse, via les en-têtes current-concurrent-requests et maximum-concurrent-requests. Ils indiquent votre marge disponible ; un niveau maximal maintenu sans que vous l’ayez déclenché est un signal fort d’abus. L’utilisation de l’endpoint HTTP brut expose directement les en-têtes de réponse :

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.

Ces signaux doivent déclencher des alertes. Un Dashboard que personne ne consulte ne permet aucune détection. Intégrez les signaux de pic de crédits et de saturation des requêtes simultanées au même circuit d’alerte que celui utilisé pour les incidents, en désignant clairement un responsable.

Réponse aux incidents

Même avec les meilleurs systèmes de sécurité et de surveillance, vous devez supposer qu’une clé finira par fuiter. Prévoir cette éventualité à l’aide d’une liste d’étapes pour limiter les dommages fournit une feuille de route qui fait gagner du temps et réduit l’impact.

Voici une procédure prédéfinie de réponse à l’exposition d’une clé API :

1. Révoquer immédiatement la clé divulguée : n’attendez pas de comprendre toute l’étendue du problème. Une clé révoquée ne peut pas générer de contenu, et cette action est réversible puisque vous pouvez toujours émettre une clé de remplacement. C’est la mesure la plus importante.
2. Passer à une nouvelle clé : si la clé divulguée gérait du trafic de production, appliquez la procédure de chevauchement en sens inverse : activez une nouvelle clé, basculez le trafic, puis confirmez que la clé divulguée est inactive. Votre code lisant la clé depuis la configuration, il s’agit d’un changement de configuration, pas de code.
3. Évaluer l’impact à partir des journaux d’utilisation : une fois la fuite contenue, quantifiez-la. Combien de temps la clé est-elle restée valide et exposée ? Quels crédits ont été consommés durant cette période, et le profil correspond-il à un trafic légitime ou à un abus ? Quels endpoints ont été sollicités ?
4. Renouveler les secrets dépendants : une clé fuit rarement seule. Si elle a été exposée dans un dépôt, un stockage de journaux ou un pipeline d’intégration continue, supposez que les secrets voisins au même endroit le sont aussi et renouvelez-les.
5. Fermer la voie de fuite : identifiez comment la clé a été divulguée et corrigez le problème, faute de quoi il se reproduira : ajoutez le fichier à .gitignore et purgez l’historique, masquez les en-têtes dans l’enregistreur, retirez le secret de l’artefact de build et renforcez les accès au système d’intégration continue.
6. Rédiger le rapport post-incident : documentez la chronologie, l’impact, la cause racine et les contrôles concrets ajoutés (restriction du périmètre, liste blanche d’adresses IP, analyseur de secrets dans l’intégration continue et rythme de rotation plus rapide).

En suivant ces étapes, vous disposerez d’une procédure de référence pour vos scénarios d’exposition d’API. 

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

L’authentification est l’un des éléments d’une évaluation plus large de la conformité ; il convient d’être prudent quant à ce qui peut ou ne peut pas être affirmé ici. Considérez les points suivants comme des repères factuels, et non comme une détermination applicable à votre cas d’usage.

ElevenLabs est conforme à SOC 2. La conformité HIPAA et des modes sans conservation des données sont disponibles pour les offres et cas d’usage éligibles. L’absence de conservation signifie que le contenu des requêtes n’est pas stocké après traitement, ce qui est important lorsque vos entrées ou les données audio générées sont sensibles.

L’applicabilité d’un mode donné dépend de votre offre, de votre configuration et de la nature de vos traitements. Confirmez l’éligibilité et les conditions exactes applicables à votre compte avant de vous y fier, et associez-les aux contrôles d’accès décrits ci-dessus. Les certifications de conformité régissent la manière dont la plateforme traite vos données ; la gestion des clés détermine qui peut agir en votre nom, et cette partie relève de votre responsabilité.

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

Les clés exclusivement côté serveur éliminent la principale surface de fuite. Les jetons à usage unique étendent cette garantie aux clients qui doivent réellement accéder à notre API. Le périmètre d’accès et la séparation par environnement limitent les dommages de toute fuite. Une rotation intégrée à la configuration rend la récupération habituelle plutôt que risquée. Les contrôles du Workspace distinguent les identités humaines et machines. L’audit transforme les abus en alertes plutôt qu’en mauvaises surprises sur votre facture. Un guide d’exploitation écrit transforme un incident en procédure.

Il s’agit de la même hygiène des identifiants qui protège tout secret de grande 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.

Lorsque vous serez prêt à l’implémenter avec les formats de requêtes réels, la référence sur l’authentification et celle sur les jetons à usage unique fournissent la liste à jour des endpoints pris en charge. Pour comprendre le modèle de requêtes simultanées que votre surveillance doit suivre, consultez ensuite la référence des modèles et le guide de démarrage rapide de l’API.

Sécurisez votre intégration ElevenAPI

Une authentification API robuste est un contrôle fondamental sur lequel reposent de nombreuses autres pratiques de sécurité. Des mesures telles que l’utilisation de clés uniquement côté serveur, le déploiement de jetons à usage unique pour les clients, la restriction au moindre privilège et l’intégration de la rotation à la gestion des clés contribuent à prévenir les risques à grande échelle.

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

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