Clés API

Présentation

Les clés API authentifient vos requêtes auprès de l’API ElevenLabs et suivent l’utilisation par rapport au quota de votre Workspace. Il en existe deux types :

• Les clés API utilisateur appartiennent à un utilisateur individuel et héritent de son accès aux ressources du Workspace. Elles sont adaptées au développement personnel et aux scripts, et peuvent recevoir une date d’expiration afin de cesser automatiquement de fonctionner après une période définie. Puisqu’elle est liée à une personne, une clé API utilisateur est affectée si l’accès de cet utilisateur change ou s’il quitte le Workspace. La création de clés API personnelles nécessite un siège complet.
• Les clés API de compte de service appartiennent à un compte de service plutôt qu’à un individu. Elles continuent donc de fonctionner indépendamment des changements d’adhésion individuels. Elles sont recommandées pour les systèmes backend, l’automatisation et les charges de travail de production. Les comptes de service sont disponibles pour les clients disposant de plusieurs sièges et sont gérés par les administrateurs du Workspace.

Votre clé API est secrète. Ne la partagez pas et ne l’exposez pas dans du code côté client (navigateurs, applications). Pour savoir comment envoyer votre clé avec une requête, consultez le guide Authentification API.

Les deux types de clés peuvent être restreints de plusieurs manières :

1. Restriction de portée : limitez les points de terminaison API auxquels la clé peut accéder.
2. Quota de crédits : définissez une limite de crédits personnalisée pour contrôler l’utilisation.
3. Liste d’autorisation IP : limitez la clé à des adresses IP ou plages CIDR spécifiques. Consultez la section Liste d’autorisation IP.

Expiration des clés API utilisateur

Les clés API utilisateur peuvent recevoir une date d’expiration afin de cesser automatiquement de fonctionner après une période définie. Cela limite la période pendant laquelle une clé divulguée ou oubliée peut être utilisée et convient à la nature temporaire des clés liées à un individu.

Définissez une expiration lorsque vous créez ou modifiez une clé depuis vos paramètres de clés API personnelles. Utilisez le sélecteur Expire After pour choisir une durée prédéfinie comprise entre 15 minutes et 30 jours, ou laissez Never (par défaut). La colonne Expires indique la date d’expiration de chaque clé.

Après son expiration, une clé ne permet plus de s’authentifier, et les requêtes effectuées avec celle-ci sont rejetées avec une erreur 401. Vous pouvez prolonger ou supprimer l’expiration en modifiant la clé avant son échéance. Sinon, renouvelez-la avec une nouvelle clé.

Renouvellement des clés API

Le renouvellement suit le même processus dans les deux cas : créez une nouvelle clé, basculez vos applications vers celle-ci, puis supprimez l’ancienne clé.

Les clés API utilisateur sont renouvelées depuis le Dashboard. Ouvrez vos paramètres de clés API personnelles, créez une nouvelle clé, puis supprimez l’ancienne une fois la bascule effectuée.

Les clés API de compte de service peuvent être renouvelées depuis le Dashboard ou via l’API :

• Dans le Dashboard, cliquez sur l’icône de votre profil en haut à droite, sélectionnez Workspace settings, puis ouvrez l’onglet Service Accounts. Créez une nouvelle clé pour le même compte de service, puis supprimez l’ancienne une fois la bascule effectuée.
• Via l’API, créez une nouvelle clé pour le même compte de service, puis supprimez l’ancienne.

Liste d’autorisation IP

Vous pouvez restreindre une clé API afin qu’elle ne fonctionne que depuis des adresses IP ou plages CIDR spécifiques. Les requêtes provenant de toute autre adresse IP seront rejetées avec une erreur 403.

Formats pris en charge

• Adresses IPv4 individuelles (par ex. 203.0.113.10)
• Adresses IPv6 individuelles (par ex. 2001:db8::1)
• Plages CIDR (par ex. 203.0.113.0/24)

Vous pouvez ajouter entre 1 et 100 entrées par clé API. Les adresses IP seules sont automatiquement normalisées en /32 (IPv4) ou /128 (IPv6).

Détection des clés divulguées

ElevenLabs participe au programme partenaire d’analyse des secrets de GitHub. Si une clé API ElevenLabs est validée dans un dépôt GitHub public, GitHub en informe ElevenLabs et la clé est automatiquement désactivée afin d’empêcher toute utilisation non autorisée.

Une clé désactivée de cette manière affiche exposed_publicly comme disable_reason. Pour restaurer l’accès, renouvelez la clé et mettez à jour vos applications afin qu’elles utilisent la nouvelle.

Désactiver vous-même une clé

Si vous pensez qu’une clé a été compromise, son détenteur peut la désactiver directement à l’aide du point de terminaison Désactiver une clé API. Appelez-le avec le paramètre de requête api_key_name=self, obligatoire comme confirmation explicite de votre intention de désactiver la clé utilisée pour authentifier la requête.

Contrôler les personnes pouvant désactiver les clés

Le paramètre third_party_disable_allowed détermine si une clé peut être désactivée par son détenteur, soit via le point de terminaison d’auto-désactivation, soit automatiquement lorsqu’elle est divulguée publiquement. Par défaut, cette option est activée pour les forfaits non Enterprise et désactivée pour les forfaits Enterprise.

Par clé : définissez third_party_disable_allowed lorsque vous créez ou mettez à jour une clé API de compte de service. Omettez-le pour utiliser la valeur par défaut du Workspace, ou transmettez clear lors de la mise à jour pour rétablir la valeur par défaut du Workspace pour une clé individuelle.

À l’échelle du Workspace : les administrateurs du Workspace peuvent remplacer simultanément le paramètre de chaque clé à l’aide du point de terminaison Définir la politique de désactivation par des tiers du Workspace :

• true autorise la désactivation de chaque clé du Workspace par son détenteur.
• false l’interdit pour chaque clé.
• null supprime le remplacement à l’échelle du Workspace, de sorte que la valeur propre à chaque clé et la valeur par défaut du forfait s’appliquent de nouveau.