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

Tokeny jednorazowe i bezpieczeństwo

Lekcja 13 z 14 Zaktualizowano 3 listopada 2026 Średnio zaawansowani
Na tej stronie
  1. Problem z kluczem API po stronie klienta
  2. Jak to działa
  3. Architektura end-to-end
  4. Zasady, których nigdy nie wolno łamać
  5. Kluczowe wnioski

Zaktualizowano 3 listopada 2026 r. na podstawie dokumentacji referencyjnej xAI Voice API. Źródła: Tokeny jednorazowe · Dokumentacja referencyjna Voice API · Wznawianie sesji.

Problem z kluczem API po stronie klienta

Aplikacja głosowa działająca w przeglądarce lub na telefonie nie może zawierać Twojego klucza API. Każdy odwiedzający może otworzyć narzędzia deweloperskie, odczytać klucz z pakietu JavaScript lub nagłówka żądania, a następnie użyć go na Twoim koncie, aż wyczerpiesz przydzielony limit. Żadna ilość zaciemniania kodu nie ochroni wartości, którą klient musi posiadać, aby wywołać API.

Rozwiązaniem xAI są tokeny jednorazowe, zwane również sekretami klienta: krótkotrwałe tokeny generowane przez Twój serwer, które autoryzują wyłącznie sesję głosową i nic więcej.

600s
domyślny czas życia
3600s
maksymalny czas życia
POST
/v1/realtime/client_secrets
wartość
token wraz z expires_at

Jak to działa

Proces sprowadza się do pięciu kroków:

  1. Twój backend (bezpieczny serwer) wywołuje POST /v1/realtime/client_secrets, używając swojego klucza API.
  2. API zwraca tymczasowy token o ograniczonym czasie życia.
  3. Twój backend wysyła ten token do klienta (przeglądarki lub aplikacji mobilnej).
  4. Klient używa tokena do nawiązania połączenia z WebSocketem Agenta Głosowego.
  5. Token wygasa po upływie wybranego przez Ciebie czasu (expires_after.seconds).

To, co może wyciec po stronie klienta, ma teraz znacznie mniejszą wartość: token wygasający w ciągu kilku minut, zdolny jedynie do otwarcia sesji głosowej, a nie Twój klucz API. Po stronie serwera wygenerowanie takiego tokena zajmuje kilka linii kodu. Zauważ, że handler rozpoczyna działanie od sprawdzenia użytkownika: bez tej kontroli Twój backend staje się po prostu publicznym dystrybutorem tokenów.

// Backend Node.js (Express)
app.post("/api/voice-token", async (req, res) => {
  // Sprawdź, czy użytkownik jest uwierzytelniony
  if (!req.user) return res.status(401).json({ error: "Unauthorized" });

  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 }  // 10 minut, wartość domyślna
      })
    }
  );

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

Klient zna jedynie Twoją własną trasę: żąda tokena, a następnie otwiera z jego użyciem połączenie WebSocket.

// Frontend (przeglądarka)
async function startVoiceSession() {
  // Poproś backend o token
  const tokenRes = await fetch("/api/voice-token", { method: "POST" });
  const { token } = await tokenRes.json();

  // Przeglądarkowy WebSocket nie obsługuje nagłówków:
  // token przesyłamy w podprotokole, z prefiksem "xai-client-secret."
  const ws = new WebSocket(
    "wss://api.x.ai/v1/realtime?model=grok-voice-latest",
    [`xai-client-secret.${token}`]
  );

  // ... konfiguracja sesji
}

Architektura end-to-end

Łącząc te elementy, proces zaczyna się od zalogowania użytkownika w Twojej aplikacji. Jego klient żąda następnie od Twojego backendu tokena głosowego, a backend sprawdza uwierzytelnienie i uprawnienia przed wygenerowaniem tokena jednorazowego poprzez API xAI. Token wraca do klienta, który używa go do otwarcia sesji Agenta Głosowego, po czym automatycznie wygasa on wraz z końcem swojego czasu życia.

Ta kontrola między żądaniem a generowaniem zamienia proste przekazywanie w punkt kontrolny – i to właśnie tam obowiązują Twoje reguły biznesowe. Możesz ograniczyć liczbę sesji głosowych na użytkownika dziennie, aby pojedyncze konto nie przepaliło Twojego miesięcznego budżetu w ciągu jednej nocy. Możesz rezerwować tokeny wyłącznie dla aktywnych subskrypcji, egzekwując swój model biznesowy poza warstwą interfejsu. Możesz stosować limitowanie częstotliwości żądań (rate limiting), aby błędny lub złośliwy klient nie mógł żądać tysięcy tokenów na minutę. Możesz też logować każdy wygenerowany token: stanowi to jedyną wiarygodną podstawę do monitorowania, wewnętrznego rozliczania i analizy incydentów.

Zasady, których nigdy nie wolno łamać

Klucz API nigdy nie trafia do klienta, w żadnej formie. Trzymaj go z dala od JavaScriptu po stronie front-endu oraz z dala od wszelkich zmiennych środowiskowych udostępnianych podczas budowania aplikacji dla przeglądarki (zmienne z prefiksem przeznaczonym do wstrzykiwania do pakietu stają się publiczne). Nie umieszczaj go również w adresach URL, logach ani komunikatach błędów wyświetlanych użytkownikom.

Po drugie, utrzymuj czas życia tokena tak krótki, jak to praktycznie możliwe. Zgodnie z dokumentacją referencyjną API, expires_after.seconds domyślnie wynosi 600 sekund, a maksimum to 3600; dokumentacja w przykładach używa wartości 300. Przede wszystkim token musi być ważny w momencie, gdy klient otwiera połączenie. Krótki czas życia zmniejsza okno czasowe, w którym przechwycony token może zostać wykorzystany.

Dokumentacja nie precyzuje, czy wygasający token zrywa już otwarte połączenie. Jeśli Twój klient musi się połączyć ponownie – po zaniku sieci lub podczas bardzo długiej sesji – poproś o nowy token i użyj wznawiania sesji: włącz resumption.enabled w session.update, zachowaj identyfikator otrzymany w conversation.created, a następnie ponownie otwórz WebSocket, dodając ?conversation_id=<id>. Poprzednie wymiany zostaną odtworzone, a model podejmie pracę tam, gdzie przerwał.

async function reconnect(conversationId) {
  const { token } = await (await fetch("/api/voice-token", { method: "POST" })).json();
  const url = `wss://api.x.ai/v1/realtime?model=grok-voice-latest&conversation_id=${conversationId}`;
  const ws = new WebSocket(url, [`xai-client-secret.${token}`]);
  ws.onopen = () => ws.send(JSON.stringify({
    type: "session.update",
    session: { resumption: { enabled: true } },  // wysyłaj ponownie przy każdym połączeniu
  }));
  return ws;
}

W przypadku TTS w trybie HTTP istnieje jeszcze prostsza alternatywa dla tokenów: proxy. Klient wysyła swój tekst do Twojego backendu, a backend wywołuje TTS i zwraca audio. Klucz nigdy nie opuszcza Twojego serwera, a Ty zyskujesz naturalne miejsce do filtrowania treści i pomiaru zużycia w trakcie procesu.

Kluczowe wnioski

  • Tokeny jednorazowe zabezpieczają dostęp do Agenta Głosowego z aplikacji po stronie klienta.
  • POST /v1/realtime/client_secrets zwraca value i expires_at; expires_after.seconds domyślnie wynosi 600, a maksimum to 3600.
  • W przeglądarce token przesyłany jest w podprotokole xai-client-secret.<token>.
  • Twój backend musi sprawdzić uwierzytelnienie i uprawnienia przed wygenerowaniem tokena.
  • Nigdy nie udostępniaj klucza API po stronie klienta, w adresach URL ani w logach.
  • W przypadku HTTP TTS validną alternatywą dla tokenów jednorazowych jest przekazywanie ruchu przez Twój backend (proxy).