Uwierzytelnianie i tokeny jednorazowe
Na tej stronie
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.secondsi 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