Ajutised lubatähed ja turvalisus
Sellel lehel
Uuendatud 3. novembril 2026, tuginedes xAI Voice API dokumentatsioonile. Allikad: Ajutised lubatähed · Voice API referents · Seansi taastamine.
Probleem API võtmega kliendipoolses rakenduses
Brauseris või telefonis töötav häälerakendus ei tohi kunagi sisaldada sinu API võtit. Iga külastaja saab avada arendaja tööriistad, lugeda võtme JavaScripti paketist või päise päisest ning kasutada seda sinu kontol seni, kuni sinu kvoot otsa saab. Ükski varjamismeetod ei kaitse väärtust, mida klient peab API kutsumiseks omama.
xAI lahenduseks on ajutised lubatähed (ehk kliendi saladused): lühiajaline lubatäht, mille genereerib sinu server ja mis annab loa ainult hääleseansiks ning mitte millekski muuks.
Kuidas see toimib
Protsess taandub viiele sammule:
- Sinu tagasüsteem (turvaline server) kutsub
POST /v1/realtime/client_secrets, kasutades sinu API võtit. - API tagastab ajutise lubatähed piiratud kehtivusajaga.
- Sinu tagasüsteem saadab selle lubatähed kliendile (brauser või mobiilirakendus).
- Klient kasutab lubatähte Voice Agent WebSocketi ühenduse loomiseks.
- Lubatäht aegub pärast sinu valitud kestust (
expires_after.seconds).
See, mis kliendipoolses osas lekib, on nüüd palju vähem väärt: lubatäht, mis aegub mõne minutiga ja suudab avada ainult hääleseansi, mitte sinu API võti. Serveris võtab selle genereerimine vaid paar koodirida. Pane tähele, et handler algab kasutaja kontrollimisega: ilma selle kontrollita on sinu tagasüsteem lihtsalt avalik lubatähtede jagaja.
// Node.js tagasüsteem (Express)
app.post("/api/voice-token", async (req, res) => {
// Kontrolli, kas kasutaja on autentitud
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 minutit, vaikimisi väärtus
})
}
);
const data = await response.json(); // { value, expires_at }
res.json({ token: data.value, expiresAt: data.expires_at });
});
Klient teab ainult sinu enda ruuti: ta küsib lubatähte ja avab seejärel sellega WebSocketi ühenduse.
// Frontend (brauser)
async function startVoiceSession() {
// Küsi tagasüsteemilt lubatäht
const tokenRes = await fetch("/api/voice-token", { method: "POST" });
const { token } = await tokenRes.json();
// Brauseri WebSocket ei aktsepteeri päiseid:
// lubatäht läheb alamprotokolli, eesliitega "xai-client-secret."
const ws = new WebSocket(
"wss://api.x.ai/v1/realtime?model=grok-voice-latest",
[`xai-client-secret.${token}`]
);
// ... seansi konfiguratsioon
}
Terviklik arhitektuur
Kokku panduna algab voog kasutaja sisselogimisega sinu rakendusse. Seejärel küsib tema klient sinu tagasüsteemilt häälelubatähte ning tagasüsteem kontrollib autentimist ja õigusi enne ajutise lubatähed genereerimist xAI API kaudu. Lubatäht liigub tagasi kliendile, kes kasutab seda Voice Agenti seansi avamiseks, ja see aegub automaatselt oma kehtivusaja lõppedes.
See kontroll päringu ja genereerimise vahel muudab lihtsa edastamise kontrollpunktiks ja just siin asuvad sinu ärireeglid. Saad piirata hääleseansside arvu kasutaja kohta päevas, nii et üks konto ei saa sinu kuueelarvet ühe ööga läbi põletada. Saad reserveerida lubatähed aktiivsetele tellimustele, rakendades oma ärimudelit mujal kui kasutajaliideses. Saad piirata päringute sagedust, et vigane või pahatahtlik klient ei saaks küsida tuhandet lubatähte minutis. Ja saad logida iga genereeritud lubatähed: see on ainus usaldusväärne alus monitooringuks, sisearvelduseks ja intsidentide analüüsiks.
Reeglid, mida mitte kunagi rikkuda
API võti ei tohi mingil kujul klienti sattuda. Hoia see eemal front-end JavaScriptist ja kõigist muutujatest, mis on brauseri buildile avalikustatud (muutujad, mille eesliide on mõeldud paketti süstimiseks, muutuvad avalikuks). Hoia see eemal ka URL-idest, logidest ja kasutajatele näidatavatest veateadetest.
Järgmiseks hoia kehtivusaeg nii lühikese kui praktiline on. API dokumentatsiooni kohaselt on expires_after.seconds vaikimisi 600 sekundit ja maksimum 3600; dokumentatsioon kasutab oma näidetes 300. Üle kõige peab lubatäht olema kehtiv hetkel, kui klient ühenduse avab. Lühike kehtivusaeg vähendab akent, mille jooksul pealtkuulatud lubatähte kasutada saab.
Dokumentatsioon ei täpsusta, kas aeguv lubatäht katkestab juba avatud ühenduse. Kui sinu klient peab uuesti ühenduma pärast võrgukatkestust või väga pika seansi ajal, küsi uus lubatäht ja kasuta seansi taastamist: luba resumption.enabled väärtuses session.update, hoia alles ID, mille said conversation.created kaudu, ja ava WebSocket uuesti parameetriga ?conversation_id=<id>. Eelmised pöörded esitatakse uuesti ja mudel jätkab sealt, kus pooleli jäi.
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 } }, // saada uuesti iga ühenduse korral
}));
return ws;
}
HTTP-režiimis TTS-i jaoks on lubatähtedest isegi lihtsam alternatiiv: proksi. Klient saadab oma teksti sinu tagasüsteemi ja sinu tagasüsteem kutsub TTS-i ning tagastab helifaili. Võti ei lahku kunagi sinu serverit ja saad loomuliku koha sisu filtreerimiseks ning kasutuse mõõtmiseks tee peal.
Peamised punktid
- Ajutised lubatähed turvavad juurdepääsu Voice Agentile kliendipoolsetest rakendustest
POST /v1/realtime/client_secretstagastabvaluejaexpires_at;expires_after.secondsvaikimisi on 600 ja maksimum 3600- Brauseris asetatakse lubatäht alamprotokolli
xai-client-secret.<token> - Sinu tagasüsteem peab enne lubatähed genereerimist kontrollima autentimist ja õigusi
- Ära kunagi avalda oma API võtit kliendil, URL-idel ega logides
- HTTP TTS-i puhul on proxy kasutamine läbi sinu tagasüsteemi kehtiv alternatiiv ajutistele lubatähtedele