Autentifikacija i privremeni tokeni
Na ovoj stranici
Dva načina autentifikacije
Voice Agent API nudi dva načina autentifikacije tvoje WebSocket veze. Koji ćeš odabrati ovisi o tome gdje se tvoj kod izvršava: na poslužitelju ili na klijentu.
Izravni API ključ (strana poslužitelja)
Najjednostavnija metoda je prosljeđivanje tvog API ključa u zaglavlju za autorizaciju prilikom otvaranja WebSocket veze. Ovo funkcionira za aplikacije na poslužitelju, gdje ključ ostaje zaštićen:
const ws = new WebSocket("wss://api.x.ai/v1/realtime", {
headers: {
"Authorization": "Bearer xai-your-api-key"
}
});
Nikada ne koristi ovu metodu u kodu koji se izvršava u pregledniku: API ključ bi bio izložen u izvornom kodu ili alatima za programere.
Privremeni tokeni (strana klijenta)
Za front-end aplikacije (preglednik, mobilni uređaji), xAI pruža privremene tokene. Tvoj backend generira kratkotrajni token koji zatim prosljeđuješ klijentu za uspostavu WebSocket veze.
Token stvaraš POST zahtjevom:
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}}'
Polje expires_after.seconds određuje koliko je dugo token valjan, u sekundama. Primjer u službenoj dokumentaciji koristi 300 sekundi (5 minuta): privremeni token namijenjen je pokrivanju glasovne sesije, a ne dugotrajnom korištenju. Ciljaj na najkraći mogući vijek trajanja koji odgovara tvojim sesijama.
Preporučena arhitektura s privremenim tokenima
Evo cjelokupnog tijeka za web aplikaciju:
// 1. Strana poslužitelja (Node.js/Express): generiranje 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 } })
}
);
// Vrati tijelo odgovora od xAI-a kakvo jest;
// ono sadrži privremeni token
res.json(await response.json());
});
// 2. Strana klijenta (preglednik): korištenje tokena
// WebSocket konstruktor u pregledniku ne prihvaća zaglavlja:
// token se šalje kao SUBPROTOCOL, s prefiksom "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");
};
}
Obnavljanje tokena
Dokumentacija ne navodi zatvara li istek tokena već uspostavljenu vezu. U svakom slučaju, tvoja aplikacija mora imati plan za slučaj prekida veze: prati događaj zatvaranja, zatraži novi token od svog backenda, a zatim se ponovno poveži:
ws.onclose = async () => {
// Veza je izgubljena ili zatvorena: zatraži novi token
const newToken = await fetchNewToken();
reconnect(newToken);
};
Najbolje sigurnosne prakse
Nekoliko ključnih pravila osigurat će sigurnost tvojih veza:
- Nikada ne izlaži svoj glavni API ključ na klijentskoj strani
- Zadrži vijek trajanja (
expires_after.seconds) što je kraće moguće: ako tvoja prosječna sesija traje pet minuta, 300 do 600 sekundi je dovoljno - Validiraj zahtjeve za token na poslužitelju (autentifikacija korisnika, ograničavanje stope zahtjeva)
- Bilježi stvaranje tokena kako bi mogao uočiti neobičnu upotrebu
- Rotiraj svoj glavni API ključ ako sumnjaš da je kompromitiran
Ključne točke
- Izravni API ključ prikladan je samo za aplikacije na poslužitelju
- Privremeni tokeni su nužni za aplikacije na strani klijenta (preglednik, mobilni uređaji)
- Postavi vijek trajanja tokena pomoću
expires_after.secondsi zadrži ga kratkim (300 sekundi u službenom primjeru) - Preporučeni tijek: tvoj backend generira token, a tvoj front-end ga prosljeđuje kao podprotokol
xai-client-secret.za otvaranje WebSocket veze - Uvijek planiraj automatsko obnavljanje tokena