Klucze API | ElevenLabs Documentation

Omówienie

Klucze API uwierzytelniają żądania do API ElevenLabs i śledzą użycie w ramach limitu obszaru roboczego. Są dwa typy:

Klucze API użytkownika należą do konkretnego użytkownika i dziedziczą jego dostęp do zasobów obszaru roboczego. Dobrze sprawdzają się w prywatnym programowaniu i skryptach; możesz ustawić im datę wygaśnięcia, aby przestały działać automatycznie po określonym czasie. Ponieważ są powiązane z osobą, zmiana dostępu użytkownika lub opuszczenie przez niego obszaru roboczego wpływa na taki klucz. Tworzenie osobistych kluczy API wymaga Full Seat.
Klucze API kont usługowych należą do konta usługowego, a nie konkretnej osoby, więc działają niezależnie od zmian w członkostwie. Polecamy je do systemów backendowych, automatyzacji i obciążeń produkcyjnych. Konta usługowe są dostępne dla klientów z wieloma stanowiskami i zarządzają nimi administratorzy obszaru roboczego.

Twój klucz API jest sekretem. Nie udostępniaj go innym ani nie ujawniaj w kodzie po stronie klienta (przeglądarkach, aplikacjach). Szczegóły wysyłania klucza z żądaniem znajdziesz w dokumentacji API Authentication.

Oba typy kluczy możesz ograniczyć na kilka sposobów:

Ograniczenie zakresu: ogranicz dostęp klucza do wybranych endpointów API.
Limit kredytów: ustaw własny limit kredytów, aby kontrolować użycie.
Lista dozwolonych adresów IP: ogranicz klucz do konkretnych adresów IP lub zakresów CIDR. Zobacz lista dozwolonych adresów IP.

Wygasające klucze API użytkownika

Kluczom API użytkownika możesz ustawić datę wygaśnięcia, aby przestawały działać automatycznie po określonym czasie. Ogranicza to okres, w którym można użyć ujawnionego lub zapomnianego klucza, i odpowiada tymczasowej naturze kluczy powiązanych z konkretną osobą.

Ustaw datę wygaśnięcia podczas tworzenia lub edycji klucza w ustawieniach osobistych kluczy API. W selektorze Expire After wybierz gotowy okres od 15 minut do 30 dni albo pozostaw Never (domyślnie). Kolumna Expires pokazuje, kiedy każdy klucz wygaśnie.

Gdy klucz przekroczy datę wygaśnięcia, przestaje uwierzytelniać, a żądania z jego użyciem są odrzucane z błędem 401. Możesz wydłużyć lub usunąć datę wygaśnięcia, edytując klucz przed jej nadejściem. W przeciwnym razie zrotuj klucz na nowy.

Data wygaśnięcia dotyczy tylko kluczy API użytkownika. Klucze API kont usługowych są przeznaczone do długotrwałych obciążeń backendowych i produkcyjnych, więc nie wygasają.

Rotacja kluczy API

Tworząc nowy klucz API na miejsce klucza, który rotujesz, skopiuj uprawnienia ze starego klucza do nowego, aby nie utracić dostępu. W przypadku kluczy kont usługowych utwórz nowy klucz dla tego samego konta usługowego.

Rotacja w obu przypadkach wygląda tak samo: utwórz nowy klucz, przełącz na niego aplikacje, a potem usuń stary klucz.

Klucze API użytkownika rotuje się z panelu. Otwórz ustawienia osobistych kluczy API, utwórz nowy klucz i usuń stary po przełączeniu.

Klucze API kont usługowych możesz rotować z panelu lub przez API:

W panelu kliknij ikonę profilu w prawym górnym rogu, wybierz Workspace settings i otwórz kartę Service Accounts. Utwórz nowy klucz dla tego samego konta usługowego, a po przełączeniu usuń stary.
Przez API utwórz nowy klucz dla tego samego konta usługowego, a następnie usuń stary.

Lista dozwolonych adresów IP

Możesz ograniczyć klucz API tak, aby działał tylko z określonych adresów IP lub zakresów CIDR. Żądania z innych adresów IP będą odrzucane z błędem 403.

Obsługiwane formaty

Pojedyncze adresy IPv4 (np. 203.0.113.10)
Pojedyncze adresy IPv6 (np. 2001:db8::1)
Zakresy CIDR (np. 203.0.113.0/24)

Do każdego klucza API możesz dodać od 1 do 100 wpisów. Same adresy IP są automatycznie normalizowane do /32 (IPv4) lub /128 (IPv6).

Prywatne zakresy IP (np. 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16) nie są akceptowane. Na listę dozwolonych można dodać tylko publiczne adresy IP.

Wykrywanie ujawnionych kluczy

ElevenLabs uczestniczy w programie partnerskim skanowania sekretów GitHub. Jeśli klucz API ElevenLabs zostanie zapisany w publicznym repozytorium GitHub, GitHub powiadomi ElevenLabs, a klucz zostanie automatycznie wyłączony, aby zapobiec nieautoryzowanemu użyciu.

Klucz wyłączony w ten sposób ma disable_reason o wartości exposed_publicly. Aby przywrócić dostęp, zrotuj klucz i zaktualizuj aplikacje, aby używały nowego.

Automatyczne wyłączanie ujawnionych kluczy działa tylko wtedy, gdy dla klucza dozwolone jest wyłączanie przez strony trzecie. Zobacz kontrolowanie, kto może wyłączać klucze.

Samodzielne wyłączanie klucza

Jeśli podejrzewasz, że klucz został naruszony, jego posiadacz może wyłączyć go bezpośrednio przez endpoint Disable API key. Wywołaj go z parametrem zapytania api_key_name=self, który jest wymaganym wyraźnym potwierdzeniem zamiaru wyłączenia klucza użytego do uwierzytelnienia żądania.

Kontrolowanie, kto może wyłączać klucze

Ustawienie third_party_disable_allowed określa, czy klucz może zostać wyłączony przez jego posiadacza — przez endpoint samodzielnego wyłączenia lub automatycznie po publicznym ujawnieniu. Domyślnie jest włączone w planach innych niż Enterprise i wyłączone w planach Enterprise.

Gdy klucz zostanie wyłączony przez stronę trzecią — automatycznie przez skanowanie sekretów GitHub lub przez endpoint samodzielnego wyłączenia — właściciel obszaru roboczego i właściciel klucza otrzymują e-mail z powiadomieniem. Samodzielne wyłączenie klucza w interfejsie webowym nie wysyła powiadomienia.

Dla klucza: ustaw third_party_disable_allowed podczas tworzenia lub aktualizacji klucza API konta usługowego. Pomiń tę wartość, aby użyć domyślnego ustawienia obszaru roboczego, albo przekaż clear podczas aktualizacji, aby zresetować ustawienie konkretnego klucza do domyślnego ustawienia obszaru roboczego.

Dla całego obszaru roboczego: administratorzy obszaru roboczego mogą jednocześnie nadpisać ustawienie każdego klucza przez endpoint Set workspace third-party disabling policy:

true pozwala wyłączyć każdy klucz w obszarze roboczym jego posiadaczowi.
false zabrania tego dla każdego klucza.
null usuwa nadpisanie dla całego obszaru roboczego, więc ponownie obowiązuje wartość każdego klucza oraz domyślne ustawienie planu.