Todentaminen ja kertakäyttöiset tunnisteet
Tällä sivulla
Kaksi todennustapaa
Voice Agent API tarjoaa kaksi tapaa todentaa WebSocket-yhteytesi. Valinta riippuu siitä, missä koodisi suoritetaan: palvelimella vai asiakaspuolella.
Suora API-avain (palvelinpuoli)
Yksinkertaisin menetelmä on välittää API-avaimesi authorization-otsikossa WebSocket-yhteyttä avattaessa. Tämä toimii palvelinsovelluksissa, joissa avain pysyy suojattuna:
const ws = new WebSocket("wss://api.x.ai/v1/realtime", {
headers: {
"Authorization": "Bearer xai-your-api-key"
}
});
Älä koskaan käytä tätä menetelmää selaimessa suoritettavassa koodissa: API-avain paljastuisi lähdekoodissa tai kehittäjätyökaluissa.
Kertakäyttöiset tunnisteet (asiakaspuoli)
Frontend-sovelluksia (selain, mobiili) varten xAI tarjoaa kertakäyttöisiä tunnisteita (ephemeral tokens). Backendisi luo lyhytikäisen tunnisteen, jonka välität asiakaspuolelle WebSocket-yhteyden avaamista varten.
Luot tunnisteen POST-pyynnöllä:
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}}'
Kenttä expires_after.seconds määrittää, kuinka kauan tunnisteen voimassaoloaika on sekunteina. Virallisen dokumentaation esimerkki käyttää 300 sekuntia (5 minuuttia): kertakäyttöisen tunnisteen tarkoitus on kattaa ääni-istunto, ei kestää ikuisesti. Pyri lyhimpään mahdolliseen voimassaoloaikaan, joka toimii istunnoillesi.
Suositeltu arkkitehtuuri kertakäyttöisillä tunnisteilla
Tässä on koko verkkosovelluksen kulku:
// 1. Palvelinpuoli (Node.js/Express): tunnisten luominen
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 } })
}
);
// Palauta xAI:n vastaus sellaisenaan;
// se sisältää kertakäyttöisen tunnisteen
res.json(await response.json());
});
// 2. Asiakaspuoli (selain): tunnisteen käyttö
// Selaimen WebSocket-konstruktori ei hyväksy otsikoita:
// tunnisteen välitys tapahtuu SUBPROTOCOL-kentässä, etuliitteellä "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");
};
}
Tunnisteiden uusiminen
Dokumentaatio ei kerro, sulkeeko vanhentuva tunnisteen jo avoimena olevan yhteyden. Joka tapauksessa sovelluksellasi on oltava suunnitelma yhteyden katkeamisen varalle: kuuntele close-tapahtumaa, pyydä backendiltäsi uusi tunnisteen ja muodosta yhteys uudelleen:
ws.onclose = async () => {
// Yhteys katkesi tai suljettiin: pyydä uusi tunnisteen
const newToken = await fetchNewToken();
reconnect(newToken);
};
Turvallisuuden parhaat käytännöt
Muutama keskeinen sääntö pitää yhteytesi turvassa:
- Älä koskaan paljasta pääasiallista API-avaintasi asiakaspuolella
- Pidä voimassaoloaika (
expires_after.seconds) mahdollisimman lyhyenä: jos keskimääräinen istuntosi kestää viisi minuuttia, 300–600 sekuntia riittää - Validoi tunnistepyynnöt palvelimella (käyttäjän todentaminen, nopeusrajoitukset)
- Lokita tunnisten luominen, jotta voit havaita epänormaalia käyttöä
- Kierrätä pääasiallinen API-avaimesi, jos epäilet sen vaarantuneen
Keskeiset asiat
- Suora API-avain sopii vain palvelinsovelluksiin
- Kertakäyttöiset tunnisteet ovat välttämättömiä asiakaspuolen sovelluksille (selain, mobiili)
- Aseta tunnisteen voimassaoloaika kohdassa
expires_after.secondsja pidä se lyhyenä (virallisessa esimerkissä 300 sekuntia) - Suositeltu kulku: backendisi luo tunnisteen, ja frontendisi välittää sen
xai-client-secret.-aliprotokollana WebSocket-yhteyden avaamiseksi - Suunnittele aina tunnisten automaattinen uusiminen