Przejdź do głównej treści
Polski— Wybierz język
Menu

Tokeny jednorazowe do połączeń WebSocket

Lekcja 5 z 12 Zaktualizowano 28 lipca 2026 Zaawansowany
Na tej stronie
  1. Problem: uwierzytelnianie klienta bez ujawniania klucza
  2. Jak działają tokeny jednorazowe
  3. Wybór odpowiedniego czasu trwania
  4. Implementacja backendowa
  5. Kluczowe wnioski

Problem: uwierzytelnianie klienta bez ujawniania klucza

Budując aplikację głosową lub działającą w czasie rzeczywistym z wykorzystaniem Grok API, musisz nawiązać połączenie WebSocket bezpośrednio z przeglądarki lub klienta mobilnego. Przekierowanie ruchu przez Twój serwer wprowadza opóźnienia, które zabijają płynność rozmowy głosowej. Jednak połączenia bezpośrednie rodzą problem z uwierzytelnianiem: nigdy nie możesz umieszczać swojego klucza API w kodzie po stronie klienta.

Powód jest prosty: każdy klucz osadzony w JavaScriptcie frontendowym, aplikacji mobilnej poddającej się dekompilacji lub dystrybuowanym binarium zostaje skompromitowany w momencie publikacji. Każdy użytkownik może otworzyć narzędzia deweloperskie przeglądarki i go odczytać. Aby rozwiązać ten problem, xAI oferuje tokeny jednorazowe: tymczasowe tokeny, z których klienci mogą korzystać, nigdy nie widząc klucza głównego.

600s
Domyślny czas trwania
3600s
Maksymalny czas trwania
POST
/v1/realtime/client_secrets
Bearer
Token tymczasowy

Jak działają tokeny jednorazowe

Architektura opiera się na jednej zasadzie: klucz API nigdy nie opuszcza Twojego serwera, a klient otrzymuje wyłącznie krótkotrwały token. Przepływ jest prosty. Klient żąda tokena od Twojego backendu, który wywołuje POST /v1/realtime/client_secrets, używając Twojego klucza API. To wywołanie jest jedynym miejscem, gdzie pojawia się klucz, i odbywa się ono całkowicie po stronie serwera. xAI zwraca token jednorazowy wraz z datą wygaśnięcia, który Twój backend przekazuje klientowi. Następnie klient otwiera połączenie WebSocket z wss://api.x.ai/v1/realtime, przedstawiając ten token. W żadnym momencie przeglądarka nie widzi klucza głównego; obsługuje token, który samoczynnie wygasa.

Wywołanie tworzące token z poziomu backendu wygląda następująco:

curl -X POST https://api.x.ai/v1/realtime/client_secrets \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"expires_after": {"seconds": 600}}'

Oraz odpowiedź:

{
  "value": "Bearer eyJhbGciOiJSUzI1NiIs...",
  "expires_at": 1712001200
}

Jeśli chodzi o czas trwania, masz trzy punkty odniesienia: nie ma udokumentowanego minimum (możliwe są nawet kilka sekund), wartość domyślna to 600 sekund (10 minut), a maksimum to 3600 sekund (1 godzina).

Wybór odpowiedniego czasu trwania

Czas życia tokena musi odpowiadać Twojemu przypadkowi użycia, a wybór ten jest realną decyzją bezpieczeństwa. Przy sporadycznych interakcjach głosowych – pytania i odpowiedzi, komendy głosowe, dyktowanie – okno 300–600 sekund w zupełności wystarczy: sesja zakończy się na długo przed wygaśnięciem. Przy długotrwałych rozmowach głosowych, takich jak obsługa klienta, wywiady czy wspomagane spotkania, celuj w 600–1800 sekund, aby uniknąć przerwania rozmowy w trakcie. Przedłużone sesje pracy – transkrypcja w czasie rzeczywistym, ciągły monitoring głosu – mogą uzasadniać 1800–3600 sekund, ale używaj maksymalnego czasu ostrożnie: wydłuża on okno eksploatacji w przypadku kradzieży tokena.

Złota zasada brzmi: zawsze wybieraj najkrótszy czas kompatybilny z Twoim przypadkiem użycia. Jeśli token zostanie przechwycony, dziesięciominutowy czas wygaśnięcia zamieni potencjalnie poważny incydent w drobną niedogodność.

Implementacja backendowa

Oto przykład bezpiecznego proxy w Node.js:

// Trasa backendowa - NIE udostępniaj po stronie klienta
app.post("/api/realtime-token", authenticateUser, async (req, res) => {
  const response = await fetch(
    "https://api.x.ai/v1/realtime/client_secrets",
    {
      method: "POST",
      headers: {
        "Authorization": `Bearer ${process.env.XAI_API_KEY}`,
        "Content-Type": "application/json"
      },
      body: JSON.stringify({
        expires_after: { seconds: 600 }
      })
    }
  );

  const token = await response.json();
  res.json({ token: token.value, expires_at: token.expires_at });
});

Trzy szczegóły w tym przykładzie stanowią o całym bezpieczeństwie konfiguracji. Klucz API znajduje się w zmiennej środowiskowej serwera, nigdy w kodzie. Middleware authenticateUser weryfikuje tożsamość użytkownika przed wydaniem tokena – bez niego każdy mógłby uzyskać tokeny i zużywać Twój limit na Twój koszt. Do klienta zwracany jest wyłącznie token jednorazowy, nigdy klucz.

Kilka pułapek pojawia się regularnie podczas przeglądów kodu. Klucz API wsunięty do frontendu „tylko na potrzeby prototypu“ nieuchronnie trafia do produkcji. Token tworzony systematycznie z maksymalnym czasem trwania dla wygody, gdy przypadek użycia wymaga ćwierci tego czasu. Punkt generowania pozostawiony bez weryfikacji uwierzytelnienia, otwarty dla wszystkich. Brak obsługi odnawiania po stronie klienta, co powoduje błędy wygaśnięcia w trakcie sesji zamiast przezroczistego ponownego połączenia: skoro odpowiedź zawiera expires_at, Twój klient ma wszystko, czego potrzebuje, aby zażądać nowego tokena przed upływem terminu, a nie po nim.

Kluczowe wnioski

  • Tokeny jednorazowe umożliwiają uwierzytelnianie WebSocket bez ujawniania klucza API
  • Punkt końcowy: POST /v1/realtime/client_secrets (wyłącznie wywołanie po stronie serwera)
  • Konfigurowalny czas trwania od kilku sekund do maksymalnie 3600 sekund (domyślnie: 600 s)
  • Twój backend działa jako proxy uwierzytelniające między klientem a xAI
  • Zawsze wybieraj najkrótszy czas trwania kompatybilny z Twoim użyciem