API-Schlüssel

Übersicht

API-Schlüssel authentifizieren Ihre Anfragen an die ElevenLabs API und erfassen die Nutzung im Rahmen des Kontingents Ihres Workspace. Es gibt zwei Arten:

• Benutzer-API-Schlüssel gehören einem einzelnen Nutzer und übernehmen dessen Zugriff auf Workspace-Ressourcen. Sie eignen sich für die persönliche Entwicklung und Skripte und können mit einem Ablaufdatum versehen werden, sodass sie nach einem festgelegten Zeitraum automatisch nicht mehr funktionieren. Da sie an eine Person gebunden sind, ist ein Benutzer-API-Schlüssel betroffen, wenn sich der Zugriff dieser Person ändert oder sie den Workspace verlässt. Das Erstellen persönlicher API-Schlüssel erfordert einen Full Seat.
• Dienstkonto-API-Schlüssel gehören zu einem Dienstkonto statt zu einer einzelnen Person. Daher funktionieren sie unabhängig von Änderungen bei einzelnen Mitgliedschaften weiter. Sie werden für Backend-Systeme, Automatisierung und Produktions-Workloads empfohlen. Dienstkonten stehen Kunden mit mehreren Seats zur Verfügung und werden von Workspace-Admins verwaltet.

Ihr API-Schlüssel ist ein Geheimnis. Geben Sie ihn nicht an andere weiter und legen Sie ihn nicht in clientseitigem Code offen (Browser, Apps). Informationen zum Senden Ihres Schlüssels mit einer Anfrage finden Sie in der Referenz zur API-Authentifizierung.

Beide Schlüsseltypen können auf mehrere Arten eingeschränkt werden:

1. Bereichsbeschränkung: Beschränken Sie, auf welche API-Endpoints der Schlüssel zugreifen kann.
2. Credit-Kontingent: Legen Sie ein individuelles Credit-Limit fest, um die Nutzung zu steuern.
3. IP-Allowlisting: Beschränken Sie den Schlüssel auf bestimmte IP-Adressen oder CIDR-Bereiche. Siehe IP-Allowlisting.

Benutzer-API-Schlüssel mit Ablaufdatum

Benutzer-API-Schlüssel können mit einem Ablaufdatum versehen werden, sodass sie nach einem festgelegten Zeitraum automatisch nicht mehr funktionieren. Dies begrenzt den Zeitraum, in dem ein offengelegter oder vergessener Schlüssel verwendet werden kann, und eignet sich für die kurzlebige Natur von Schlüsseln, die an eine Person gebunden sind.

Legen Sie beim Erstellen oder Bearbeiten eines Schlüssels in Ihren persönlichen API-Schlüssel-Einstellungen ein Ablaufdatum fest. Wählen Sie im Selektor Expire After eine Vorgabe zwischen 15 Minuten und 30 Tagen oder lassen Sie Never ausgewählt (Standard). Die Spalte Expires zeigt, wann jeder Schlüssel abläuft.

Nach Ablauf eines Schlüssels kann er nicht mehr zur Authentifizierung verwendet werden. Anfragen damit werden mit einem 401-Fehler abgelehnt. Sie können das Ablaufdatum verlängern oder entfernen, indem Sie den Schlüssel vor seinem Ablauf bearbeiten. Andernfalls rotieren Sie ihn zu einem neuen Schlüssel.

API-Schlüssel rotieren

Die Rotation folgt in beiden Fällen demselben Muster: Erstellen Sie einen neuen Schlüssel, stellen Sie Ihre Anwendungen darauf um und löschen Sie dann den alten Schlüssel.

Benutzer-API-Schlüssel werden im Dashboard rotiert. Öffnen Sie Ihre persönlichen API-Schlüssel-Einstellungen, erstellen Sie einen neuen Schlüssel und löschen Sie den alten, sobald Sie umgestellt haben.

Dienstkonto-API-Schlüssel können im Dashboard oder über die API rotiert werden:

• Klicken Sie im Dashboard oben rechts auf Ihr Profilsymbol, wählen Sie Workspace settings und öffnen Sie den Tab Service Accounts. Erstellen Sie einen neuen Schlüssel für dasselbe Dienstkonto und löschen Sie den alten, sobald Sie umgestellt haben.
• Erstellen Sie über die API einen neuen Schlüssel für dasselbe Dienstkonto und löschen Sie den alten.

IP-Allowlisting

Sie können einen API-Schlüssel so beschränken, dass er nur von bestimmten IP-Adressen oder CIDR-Bereichen funktioniert. Anfragen von jeder anderen IP werden mit einem 403-Fehler abgelehnt.

Unterstützte Formate

• Einzelne IPv4-Adressen (z. B. 203.0.113.10)
• Einzelne IPv6-Adressen (z. B. 2001:db8::1)
• CIDR-Bereiche (z. B. 203.0.113.0/24)

Sie können pro API-Schlüssel zwischen 1 und 100 Einträge hinzufügen. IP-Adressen ohne Präfix werden automatisch auf /32 (IPv4) oder /128 (IPv6) normalisiert.

Offengelegte Schlüssel erkennen

ElevenLabs nimmt am Partnerprogramm für Secret Scanning von GitHub teil. Wenn ein ElevenLabs API-Schlüssel in ein öffentliches GitHub-Repository übertragen wird, benachrichtigt GitHub ElevenLabs und der Schlüssel wird automatisch deaktiviert, um unbefugte Nutzung zu verhindern.

Ein auf diese Weise deaktivierter Schlüssel meldet als disable_reason den Wert exposed_publicly. Um den Zugriff wiederherzustellen, rotieren Sie den Schlüssel und aktualisieren Sie Ihre Anwendungen, damit sie den neuen verwenden.

Einen Schlüssel selbst deaktivieren

Wenn Sie glauben, dass ein Schlüssel kompromittiert wurde, kann der Inhaber des Schlüssels ihn über den Endpoint API-Schlüssel deaktivieren direkt deaktivieren. Rufen Sie ihn mit dem Abfrageparameter api_key_name=self auf. Dieser ist als ausdrückliche Bestätigung erforderlich, dass Sie den Schlüssel deaktivieren möchten, mit dem die Anfrage authentifiziert wird.

Steuern, wer Schlüssel deaktivieren kann

Die Einstellung third_party_disable_allowed steuert, ob ein Schlüssel von seinem Inhaber deaktiviert werden kann — entweder über den Endpoint zur Selbstdeaktivierung oder automatisch, wenn er öffentlich offengelegt wird. Standardmäßig ist dies für Nicht-Enterprise-Tarife aktiviert und für Enterprise-Tarife deaktiviert.

Pro Schlüssel: Legen Sie third_party_disable_allowed fest, wenn Sie einen Dienstkonto-API-Schlüssel erstellen oder aktualisieren. Lassen Sie es weg, um den Workspace-Standard zu verwenden, oder übergeben Sie bei einer Aktualisierung clear, um einen einzelnen Schlüssel auf den Workspace-Standard zurückzusetzen.

Workspace-weit: Workspace-Admins können die Einstellung aller Schlüssel gleichzeitig über den Endpoint Workspace-Richtlinie für Deaktivierung durch Dritte festlegen überschreiben:

• true erlaubt, dass jeder Schlüssel im Workspace durch seinen Inhaber deaktiviert wird.
• false verbietet dies für jeden Schlüssel.
• null entfernt die Workspace-weite Überschreibung, sodass wieder der eigene Wert jedes Schlüssels und der Tarifstandard gelten.