Uwierzytelnianie API i zarządzanie kluczami w ElevenAPI

Uwierzytelnianie API to sposób, w jaki usługa sprawdza, czy przychodzące żądanie ma prawo działać na danym koncie. Na przykład w ElevenAPI dane uwierzytelniające API pozwalają na zużywanie kredytów, generowanie mowy i muzyki na dużą skalę, a w niektórych wdrożeniach także na dostęp do wrażliwego audio.

Wykradziony klucz to realny koszt — ktoś może generować treści na twoim koncie. Może też dać zbyt szeroki dostęp do twoich platform, co grozi wyciekiem danych i innymi atakami. Już w 2020 roku ponad 90% deweloperów korzystało z API codziennie. Teraz, gdy AI i nowe protokoły są wszędzie, API są po prostu wszędzie.

W tym artykule pokazujemy, jak poprawnie uwierzytelniać API i zarządzać kluczami przez cały ich cykl życia: od zakresu, przez rotację, kontrolę dostępu, audyt, aż po reagowanie na incydenty. Dzięki temu poprawnie wdrożysz uwierzytelnianie i zarządzanie kluczami w swoim zespole. Dla wygody miej pod ręką dokumentację uwierzytelniania oraz dokumentację tokenów jednorazowych.

W skrócie

• ElevenAPI uwierzytelnia każde żądanie za pomocą jednego sekretu — nagłówka xi-api-key. Każdy, kto ma klucz, może wydawać kredyty i generować audio na twoim koncie.
• Nigdy nie umieszczaj długoterminowego klucza API w przeglądarce, aplikacji mobilnej ani żadnym pliku, który użytkownik może podejrzeć. Trzymaj klucze tylko na swoim serwerze.
• W aplikacjach po stronie klienta używaj tylko krótkoterminowych, jednorazowych tokenów generowanych po stronie serwera — nigdy długoterminowego klucza.
• Możesz ograniczyć skutki wycieku, nadając kluczom minimalne uprawnienia, rozdzielając je na środowiska i regularnie je rotując.
• Audyt i wykrywanie anomalii pomagają zapobiegać wyciekom kluczy i niespodziankom.

Czym jest uwierzytelnianie API?

Uwierzytelnianie API to sposób, w jaki usługa sprawdza, czy żądanie może działać na danym koncie, zanim zacznie je obsługiwać. Klient podaje dane uwierzytelniające, usługa je weryfikuje i po potwierdzeniu odpowiada.

Mówiąc prosto: czy to żądanie ma prawo działać na tym koncie? To nie to samo co autoryzacja API, która określa, co uwierzytelnione żądanie może zrobić w twoim systemie.

Czym jest zarządzanie kluczami?

Zarządzanie kluczami to zbiór praktyk, które stosujesz, by kontrolować klucz API przez cały jego cykl życia. Określa, jak tworzysz, przechowujesz, używasz, rotujesz i odbierasz dostęp do kluczy. Te systemy mają chronić klucz API od początku do końca.

Dzięki dobremu zarządzaniu kluczami możesz zapobiec wyciekom i zmniejszyć ryzyko, że klucz stanie się publiczny.

Dlaczego bezpieczeństwo kluczy API jest ważne: model zagrożeń

Skoro już wiemy, czym jest uwierzytelnianie i zarządzanie kluczami, warto jasno powiedzieć, co się dzieje, gdy klucz zostanie źle użyty. Najpierw przyjrzyjmy się zagrożeniom — każda kolejna praktyka ma wtedy jasny cel: zmniejsza szansę wycieku lub ogranicza jego skutki.

ElevenAPI uwierzytelnia przez jeden mechanizm — nagłówek xi-api-key. Każdy, kto ma klucz, jest uprawniony, nie ma drugiego czynnika.

Mając twój klucz, ktoś może wydawać twoje kredyty. Text to Speech, Speech to Text, muzyka i efekty dźwiękowe są rozliczane, a atakujący z ważnym kluczem może generować bez końca, aż wyczerpie się limit lub saldo.

Może generować na dużą skalę, a nasz model limitowania oparty jest na współbieżności, nie na prostym limicie żądań na minutę. Klucz z limitem 5 współbieżnych żądań dla danej rodziny modeli pozwala na sporo równoczesnych generacji, a atakujący, który to rozumie, zrównolegli nadużycie.

Może generować treści na twoim koncie. Każde audio wygenerowane twoim kluczem jest przypisane do twojego workspace, a w zależności od użytych głosów i treści może to być problem wizerunkowy, a czasem nawet prawny.

Klucze wyciekają w prosty sposób — to te same błędy, które dotyczą innych danych uwierzytelniających:

• Klucze API w kodzie po stronie klienta: Klucz umieszczony w paczce przeglądarkowej, binarce mobilnej czy SPA jest w praktyce publiczny. Minifikacja nie ukrywa kodu.
• Klucze API w repozytoriach: Klucze na sztywno w kodzie wrzuconym do Gita, także w prywatnych repo, które potem stają się publiczne lub są szeroko klonowane, oraz w plikach typu .env, które nie miały być śledzone.
• Klucze API w logach i śladach: Loggery żądań, trackery błędów i narzędzia do obserwowalności często zapisują nagłówki HTTP. Klucz w xi-api-key trafia do twoich logów, do dostawcy APM i do każdego, kto ma do nich dostęp.
• Klucze API w CI i na zrzutach ekranu: Logi z budowania, zgłoszenia do supportu, współdzielone terminale.

Każda sekcja poniżej pokazuje, jak zmniejszyć prawdopodobieństwo lub skutki któregoś z tych przypadków.

Zasada numer jeden: trzymaj klucze API po stronie serwera

Reszta artykułu to sposoby na ograniczenie ryzyka związanego z kluczami API. Ta jedna zasada jest podstawą i powinna być wdrożona zawsze.

Ponieważ mechanizm jest prosty, zasada jest jasna: długoterminowy klucz API powinien być tylko na serwerze, który kontrolujesz. Nigdy nie umieszczaj go w przeglądarce, aplikacji mobilnej, desktopowej ani w żadnym pliku, który użytkownik może pobrać i podejrzeć. Jeśli klucz jest w kodzie po stronie klienta, traktuj go jak już przejęty.

SDK automatycznie czyta ELEVENLABS_API_KEY, więc najprostszy kod nie przekazuje nic i inicjalizuje klienta tylko raz.

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",
});

W produkcji klucz powinien być pobierany z menedżera sekretów (np. AWS Secrets Manager, GCP Secret Manager, HashiCorp Vault lub odpowiednika na twojej platformie) przy starcie procesu, a nie wpisany na sztywno w obraz lub .env w repo.

Tokeny jednorazowe dla aplikacji po stronie klienta

Zasada numer jeden jest bezwzględna, ale są przypadki, gdy klient musi sięgnąć do ElevenAPI: przeglądarka odtwarzająca Text to Speech, aplikacja mobilna nagrywająca audio do transkrypcji, agent działający w zakładce użytkownika. Długoterminowy klucz nie może tam trafić. Rozwiązaniem jest przekazanie klientowi tokenu, który nawet po wycieku nie stanowi dużego ryzyka: krótkoterminowego, jednorazowego tokenu.

Twój serwer trzyma długoterminowy klucz, uwierzytelnia i autoryzuje użytkownika według twojej logiki sesji, a potem generuje krótkożyjący token i przekazuje tylko ten token do klienta. Token szybko wygasa i ma ograniczony zakres, więc nawet jeśli wycieknie, jest mało wart. Zobacz dokumentację tokenów jednorazowych, by sprawdzić obsługiwane endpointy i dokładny format żądania.

Oto podstawowa logika endpointu brokera. Autoryzuje użytkownika według twojej logiki sesji, potem generuje token przez opisany endpoint. Żądanie wychodzi z serwera z długoterminowym xi-api-key, a do klienta trafia tylko krótkożyjący token.

// ... 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() });
});

Przeglądarka używa potem tego tokenu do połączenia, a długoterminowy klucz nigdy nie trafia na stronę.

Ograniczanie uprawnień kluczy do minimum

Zasada minimalnych uprawnień mówi, że każdy klucz powinien mieć tylko te uprawnienia, które są mu potrzebne — nic więcej. ElevenAPI pozwala ustawić ograniczenia na podstawie uprawnień, które określają, co klucz może, a czego nie.

Jeden wszechmocny klucz to najgorszy scenariusz — i niestety domyślny. Lepiej założyć, że każdy klucz kiedyś wycieknie, i zadbać, by wtedy mógł zrobić tylko to, co musi.

Zacznij od ograniczenia zakresu, czyli tego, które endpointy API klucz może wywoływać. Klucz używany tylko do transkrypcji nie potrzebuje dostępu do Text to Speech; klucz do muzyki nie musi mieć dostępu do zarządzania głosami.

Kolejny krok to limit kredytów. Ustawiając limit kredytów na klucz, ograniczasz potencjalne straty finansowe i zabezpieczasz się przed błędami w swoim kodzie.

Biała lista IP to jeszcze większa kontrola. Możesz ograniczyć klucz do konkretnych adresów IP lub zakresów CIDR — żądania spoza listy dostaną 403. To funkcja Enterprise w fazie testów, dostępna przez opiekuna konta.

Nie używaj tego samego klucza w development, stagingu i produkcji. Wydaj osobny klucz na każde środowisko, z własnym zakresem i limitem. Dzięki temu wyciek z laptopa dewelopera nie zagrozi produkcji, możesz rotować klucze niezależnie, a logi są czytelniejsze, bo ruch jest już podzielony według źródła.

Rotacja kluczy API

Rotacja kluczy to regularna wymiana klucza na nowy. To też coś, co robisz od razu, gdy podejrzewasz wyciek.

Regularna rotacja skraca czas, w którym niezauważony wyciek może być wykorzystany. Rotacja jest bezbolesna tylko wtedy, gdy twój kod jest na to gotowy — zaplanuj ją wcześniej.

Podstawowa technika to nakładanie się kluczy, co pozwala przełączyć się bez przestojów:

1. Wygeneruj nowy klucz API: Dodaj nowy klucz obok starego, z tym samym zakresem, limitem i ograniczeniami IP. Oba są teraz ważne.
2. Zaktualizuj klucz: Wdróż nowy klucz, aktualizując sekret w menedżerze sekretów i pozwól instancjom go pobrać (przez restart, ponowny odczyt lub odświeżenie sekretu — zależnie od twojej konfiguracji).
3. Sprawdź ruch: Upewnij się, że ruch idzie już przez nowy klucz. Obserwuj, czy stary klucz przestał być używany.
4. Usuń dostęp starego klucza: Cofnij stary klucz, gdy przez bezpieczny czas nie ma na nim ruchu.

Ponieważ oba klucze są ważne w czasie nakładki, nie ma momentu, w którym żądania nie przejdą przez brak klucza. Nakładka ma jeszcze jedną zaletę: źle skonfigurowana instancja ujawni się, bo dalej używa starego klucza — znajdziesz ją, zanim go wyłączysz.

Aby rotacja była bezproblemowa, zorganizuj kod tak, by rotacja była zmianą konfiguracji, a nie kodu. Klucz czytaj z jednego miejsca, które można odświeżyć, i jednym przełącznikiem decyduj, który sekret jest aktywny.

// 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;
}

Podczas nakładki trzymasz oba: PRIMARY i SECONDARY, a przełączasz ELEVENLABS_KEY_ACTIVE. Kod aplikacji się nie zmienia.

Domyślnie rotuj backendowe klucze co 90 dni, częściej dla kluczy o dużej wartości lub szerokim dostępie, i natychmiast po wycieku. Możesz to zautomatyzować zadaniem, które generuje, wdraża, sprawdza i cofa klucze — wtedy rotacja staje się procesem w tle.

Kontrola dostępu i uprawnienia workspace

Ograniczanie zakresu i rotacja zabezpieczają pojedyncze klucze, a kontrola workspace decyduje, kto może je w ogóle tworzyć. To miejsce na wdrożenie polityki organizacji, która wpłynie na wszystkie praktyki zarządzania kluczami.

Najpierw rozdziel dane ludzkie i maszynowe. Ludzie logują się do dashboardu własnym kontem i uprawnieniami; usługi uwierzytelniają się kluczami lub — lepiej — kontami serwisowymi. Nie pozwalaj, by usługa działała na kluczu wygenerowanym z prywatnego dostępu osoby, ani by ludzie dzielili jeden klucz maszynowy. Chodzi o offboarding: gdy ktoś odchodzi lub usługa jest wycofywana, chcesz cofnąć dokładnie ten dostęp, bez skutków ubocznych.

Konta serwisowe mają ten sam cel. Dają maszynom tożsamość niezależną od ludzi, z własnym zakresem, co pozwala zachować przejrzystość audytu.

Następnie przypisuj dostęp do ról, nie do pojedynczych osób. Workspace obsługuje uprawnienia grup i członków właśnie po to. Daj każdej grupie minimalny dostęp potrzebny do pracy, regularnie przeglądaj członkostwo i dąż do tego, by żaden pojedynczy dostęp — ludzki czy maszynowy — nie dawał więcej niż wymaga rola.

Audyt i wykrywanie

W poprzednich krokach pokazaliśmy, jak ograniczyć skutki wycieku. Teraz — jak wykryć, czy wyciek w ogóle miał miejsce. Dobre wykrywanie opiera się na trzech nawykach.

Po pierwsze: zapisuj, który klucz (po identyfikatorze, nigdy po wartości sekretu) obsłużył jaką klasę żądań, skąd i w jakiej ilości. Usuń nagłówek xi-api-key z każdego logowania i śledzenia. Reguła anonimizacji w twoim middleware HTTP i konfiguracji APM zamyka najczęstszą drogę wycieku kluczy do logów.

Po drugie: monitoruj zużycie kredytów pod kątem anomalii. Śledź spalanie kredytów na klucz w czasie i alarmuj przy odchyleniach od normy: nagły skok, generowanie o nietypowych godzinach, klucz, który miał być nieaktywny, nagle zaczyna działać.

Po trzecie: obserwuj nagłówki współbieżności. W każdej odpowiedzi zwracamy bieżącą i maksymalną liczbę równoczesnych żądań w nagłówkach current-concurrent-requests i maximum-concurrent-requests. Pokazują, ile masz zapasu, a długotrwałe osiągnięcie maksimum bez twojej inicjatywy to mocny sygnał nadużycia. Używając surowego endpointu HTTP, widzisz te nagłówki bezpośrednio:

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.

To powinno wywołać alarm. Dashboard, którego nikt nie ogląda, nie wykryje niczego. Podłącz alarmy o skoku kredytów i nasyceniu współbieżności do tej samej ścieżki powiadomień, co awarie — z jasnym właścicielem.

Reagowanie na incydenty

Nawet przy najlepszych zabezpieczeniach i monitoringu musisz założyć, że klucz kiedyś wycieknie. Plan na taką sytuację — lista kroków ograniczających szkody — daje ci gotowy scenariusz działania i oszczędza czas.

Oto gotowy plan reagowania na wyciek klucza API:

1. Natychmiast cofnij wyciekły klucz: Nie czekaj na pełny obraz sytuacji. Cofnięty klucz nie generuje już nic, a cofnięcie jest odwracalne — zawsze możesz wydać nowy. To najważniejszy krok.
2. Rotuj na nowy klucz: Jeśli wyciekły klucz obsługiwał produkcję, użyj procedury nakładki w drugą stronę: uruchom nowy klucz, przełącz ruch, potem upewnij się, że stary jest martwy. Ponieważ kod czyta klucz z konfiguracji, to tylko zmiana configu, nie kodu.
3. Oceń skalę szkód na podstawie logów: Gdy wyciek jest opanowany, policz go. Jak długo klucz był ważny i widoczny? Ile kredytów zużyto w tym czasie i czy wzorzec pasuje do normalnego ruchu, czy do nadużycia? Jakie endpointy były używane?
4. Rotuj powiązane sekrety: Klucz rzadko wycieka sam. Jeśli był w repo, logach lub CI, załóż, że inne sekrety w tym miejscu też są zagrożone — rotuj je również.
5. Zamknij drogę wycieku: Znajdź, jak klucz wyciekł, i napraw to, inaczej sytuacja się powtórzy: dodaj plik do .gitignore i wyczyść historię, dodaj anonimizację nagłówków w loggerze, przenieś sekret poza artefakt builda, ogranicz dostęp do CI.
6. Napisz post-mortem: Opisz przebieg zdarzenia, skalę szkód, przyczynę i konkretne zabezpieczenia wdrożone po incydencie (zawężenie zakresu, biała lista IP, skaner sekretów w CI, szybsza rotacja).

Dzięki tym krokom masz gotowy plan działania na wypadek wycieku klucza API.

Zgodność: SOC 2, HIPAA i retencja danych

Uwierzytelnianie to tylko jeden z elementów szerszej oceny zgodności — warto wiedzieć, co można, a czego nie można tu zadeklarować. Potraktuj poniższe jako punkt wyjścia, nie gotową odpowiedź dla twojego przypadku.

ElevenLabs jest zgodny z SOC 2. Dla wybranych planów i zastosowań dostępna jest zgodność z HIPAA i tryb zerowej retencji. Tryb zerowej retencji oznacza, że treść żądania nie jest przechowywana po przetworzeniu — to ważne, gdy twoje dane wejściowe lub wygenerowane audio są wrażliwe.

To, czy dany tryb ma zastosowanie, zależy od twojego planu, konfiguracji i tego, co przetwarzasz. Przed użyciem sprawdź, czy możesz z nich skorzystać i jakie są dokładne warunki — oraz połącz je z kontrolą dostępu opisaną wyżej. Certyfikaty zgodności określają, jak platforma obsługuje twoje dane; zarządzanie kluczami decyduje, kto może działać w twoim imieniu — za to odpowiadasz ty.

Jak wygląda dobre bezpieczeństwo kluczy API

Klucze tylko po stronie serwera eliminują największe ryzyko wycieku. Tokeny jednorazowe rozszerzają tę ochronę na klientów, którzy naprawdę muszą korzystać z naszego API. Ograniczanie zakresu i rozdzielanie środowisk ogranicza skutki wycieku. Rotacja w konfiguracji sprawia, że odzyskiwanie jest rutyną, nie ryzykiem. Kontrola workspace rozdziela tożsamości ludzi i maszyn. Audyt zamienia nadużycie w alarm, a nie niespodziankę na fakturze. Spisany plan działania zamienia incydent w procedurę.

To te same zasady higieny, które chronią każdy cenny sekret — tylko tu chodzi o klucz, który wydaje pieniądze i generuje audio na dużą skalę.

Gdy będziesz gotowy wdrożyć to w praktyce, dokumentacja uwierzytelniania i tokenów jednorazowych zawiera aktualną listę obsługiwanych endpointów. Jeśli chcesz zrozumieć model współbieżności, który warto monitorować, zajrzyj do dokumentacji modeli i szybkiego startu API.

Zabezpiecz swoją integrację z ElevenAPI

Silne uwierzytelnianie API to podstawa, na której opierają się inne praktyki bezpieczeństwa. Takie działania jak klucze tylko po stronie serwera, tokeny jednorazowe dla klientów, minimalne uprawnienia i rotacja kluczy pomagają ograniczyć ryzyko na dużą skalę.

Więcej informacji o obsługiwanych endpointach i dokładnym formacie nagłówka znajdziesz w dokumentacji ElevenAPI. Jeśli chcesz zacząć, poproś o klucz API od ElevenLabs i zacznij budować już dziś.

FAQ: uwierzytelnianie API i zarządzanie kluczami