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

Uwierzytelnianie i tokeny jednorazowe

Lekcja 2 z 16 Zaktualizowano 30 lipca 2026 Programista
Na tej stronie
  1. Dwa sposoby uwierzytelniania
  2. Zalecana architektura z tokenami jednorazowymi
  3. Najlepsze praktyki bezpieczeństwa
  4. Kluczowe wnioski

Dwa sposoby uwierzytelniania

Voice Agent API oferuje dwa sposoby uwierzytelnienia połączenia WebSocket. Wybór metody zależy od miejsca uruchomienia kodu: po stronie serwera czy klienta.

Bezpośredni klucz API (strona serwera)

Najprostszą metodą jest przekazanie klucza API w nagłówku autoryzacji podczas otwierania połączenia WebSocket. Metoda ta sprawdza się w aplikacjach serwerowych, gdzie klucz pozostaje chroniony:

const ws = new WebSocket("wss://api.x.ai/v1/realtime", {
  headers: {
    "Authorization": "Bearer xai-your-api-key"
  }
});

Nigdy nie używaj tej metody w kodzie działającym w przeglądarce: klucz API zostałby ujawniony w kodzie źródłowym lub narzędziach deweloperskich.

Tokeny jednorazowe (strona klienta)

W przypadku aplikacji front-endowych (przeglądarka, urządzenia mobilne) xAI udostępnia tokeny jednorazowe (ephemeral tokens). Twój backend generuje krótkotrwały token, który następnie przekazujesz klientowi do nawiązania połączenia WebSocket.

Token tworzysz, wysyłając żądanie POST:

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": 300}}'

Pole expires_after.seconds określa czas ważności tokenu w sekundach. Przykład w oficjalnej dokumentacji używa wartości 300 sekund (5 minut): token jednorazowy ma obsługiwać sesję głosową, a nie być trwały. Dąż do ustawienia jak najkrótszego czasu życia, który wystarczy dla Twoich sesji.

Zalecana architektura z tokenami jednorazowymi

Oto kompletny przepływ dla aplikacji internetowej:

// 1. Strona serwera (Node.js/Express): generowanie tokena
app.post("/api/realtime-token", 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 } })
    }
  );
  // Zwróć ciało odpowiedzi xAI bez zmian;
  // zawiera ono token jednorazowy
  res.json(await response.json());
});

// 2. Strona klienta (przeglądarka): użycie tokena
// Konstruktor WebSocket w przeglądarce nie przyjmuje nagłówków:
// token przekazuje się w SUBPROTOCOL, z prefiksem "xai-client-secret."
async function startVoiceSession(ephemeralToken) {
  const ws = new WebSocket(
    "wss://api.x.ai/v1/realtime",
    [`xai-client-secret.${ephemeralToken}`]
  );

  ws.onopen = () => {
    console.log("Voice session started");
  };
}

Odświeżanie tokenów

Dokumentacja nie precyzuje, czy wygasający token zamyka już otwarte połączenie. Niezależnie od tego, Twoja aplikacja musi mieć plan działania na wypadek utraty połączenia: nasłuchuj zdarzenia zamknięcia, poproś backend o nowy token, a następnie połącz się ponownie:

ws.onclose = async () => {
  // Połączenie utracone lub zamknięte: żądaj nowego tokena
  const newToken = await fetchNewToken();
  reconnect(newToken);
};

Najlepsze praktyki bezpieczeństwa

Kilka podstawowych zasad zapewni bezpieczeństwo Twoich połączeń:

  • Nigdy nie udostępniaj głównego klucza API po stronie klienta
  • Utrzymuj czas życia (expires_after.seconds) tak krótki, jak to możliwe: jeśli średnia sesja trwa pięć minut, 300–600 sekund w zupełności wystarczy
  • Weryfikuj żądania tokenów na serwerze (uwierzytelnianie użytkownika, limitowanie liczby żądań)
  • Rejestruj tworzenie tokenów, aby wykrywać nieprawidłowe użycie
  • Rotuj główny klucz API, jeśli podejrzewasz jego kompromitację

Kluczowe wnioski

  • Bezpośredni klucz API nadaje się wyłącznie do aplikacji serwerowych
  • Tokeny jednorazowe są niezbędne w aplikacjach klienckich (przeglądarka, urządzenia mobilne)
  • Czas życia tokenu ustawiasz za pomocą expires_after.seconds i powinien on być krótki (300 sekund w oficjalnym przykładzie)
  • Zalecany przepływ: backend generuje token, a front-end przekazuje go jako podprotokół xai-client-secret. do otwarcia połączenia WebSocket
  • Zawsze planuj automatyczne odświeżanie tokenów