Väliaikaiset tunnisteet ja tietoturva
Tällä sivulla
Päivitetty 3. marraskuuta 2026 xAI Voice API -viitteiden perusteella. Lähteet: Ephemeral Tokens · Voice API reference · Session Resumption.
Ongelma: API-avain asiakaspuolella
Selaimessa tai puhelimessa toimiva äänisovellus ei voi sisältää API-avaintasi. Kuka tahansa vierailija voi avata kehittäjätyökalut, lukea avaimen JavaScript-paketista tai pyyntöotsikosta ja käyttää sitä tililläsi, kunnes kiintiösi loppuu. Mikään häivyttämismenetelmä ei suojaa arvoa, joka asiakkaan on pakko saada API-kutsua varten.
xAI:n ratkaisu ovat väliaikaiset tunnisteet (ephemeral tokens), joita kutsutaan myös asiakassalaisuuksiksi (client secrets): palvelimesi luoma lyhytikäinen tunnistekoodi, joka valtuuttaa ainoastaan ääni-istunnon eikä mitään muuta.
Miten se toimii
Prosessi tiivistyy viiteen vaiheeseen:
- Palvelinpuolesi (turvallinen palvelin) kutsuu osoitetta
POST /v1/realtime/client_secretskäyttäen API-avaintasi - API palauttaa väliaikaisen tunnisteen, jolla on rajoitettu voimassaoloaika
- Palvelinpuolesi lähettää tämän tunnisteen asiakkaalle (selain tai mobiilisovellus)
- Asiakas käyttää tunnistetta muodostaakseen yhteyden Voice Agent WebSocketiin
- Tunniste vanhentuu valitsemasi ajan (
expires_after.seconds) kuluttua
Nyt asiakaspuolella mahdollisesti vuotava tieto on paljon vähemmän arvokasta: tunnistekoodi, joka vanhenee minuuteissa ja voi avata vain ääni-istunnon, ei API-avaintasi. Palvelimella sen luominen vaatii vain muutaman koodirivin. Huomaa, että käsittelijän tulee ensin tarkistaa käyttäjä: ilman tätä tarkistusta palvelinpuolesi on vain julkinen tunnistejakelija.
// Node.js-palvelin (Express)
app.post("/api/voice-token", async (req, res) => {
// Tarkista, että käyttäjä on kirjautunut sisään
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 minuuttia, oletusarvo
})
}
);
const data = await response.json(); // { value, expires_at }
res.json({ token: data.value, expiresAt: data.expires_at });
});
Asiakas tuntee vain oman reittisi: se pyytää tunnistetta ja avaa sen jälkeen WebSocket-yhteyden sitä käyttäen.
// Asiakaspuoli (selain)
async function startVoiceSession() {
// Pyydä tunnistetta palvelinpuolelta
const tokenRes = await fetch("/api/voice-token", { method: "POST" });
const { token } = await tokenRes.json();
// Selaimen WebSocket ei hyväksy otsikoita:
// tunniste laitetaan aliprotokollaan etuliitteellä "xai-client-secret."
const ws = new WebSocket(
"wss://api.x.ai/v1/realtime?model=grok-voice-latest",
[`xai-client-secret.${token}`]
);
// ... istunnon määritys
}
End-to-end-arkkitehtuuri
Kokonaisuutena virta alkaa siitä, että käyttäjä kirjautuu sovellukseesi. Sen jälkeen hänen asiakasohjelmistonsa pyytää palvelinpuoleltasi äänitunnistetta, ja palvelinpuoli tarkistaa tunnistautumisen ja käyttöoikeudet ennen väliaikaisen tunnisteen luomista xAI-rajapinnan kautta. Tunniste palaa asiakkaalle, joka käyttää sitä Voice Agent -istunnon avaamiseen, ja se vanhenee automaattisesti voimassaoloaikansa päätyttyä.
Tämä tarkistus pyynnön ja luonnin välillä muuttaa yksinkertaisen välityspisteen turvatarkastuspisteeksi, ja juuri siihen liiketoimintasääntösi kuuluvat. Voit rajoittaa ääni-istuntojen määrää käyttäjää kohti päivässä, jotta yksittäinen tili ei polta kuukausibudjettiasi yhdessä yössä. Voit varata tunnisteet aktiivisille tilauksille ja valvoa liiketoimintamalliasi muualla kuin käyttöliittymässä. Voit rajoittaa pyyntöjen määrää, jotta viallinen tai haitallinen asiakas ei voi pyytää tuhatta tunnistetta minuutissa. Ja voit lokittaa jokaisen luomasi tunnisteen: se on ainoa luotettava perustasi seurannalle, sisäiselle laskutukselle ja tapahtumien analysoinnille.
Säännöt, joita ei saa koskaan rikkoa
API-avain ei koskaan päädy asiakkaalle missään muodossa. Pidä se poissa front-end-JavaScriptistä ja kaikista selaimen buildille altistetuista ympäristömuuttujista (muuttujat, jotka on merkitty injektioitavaksi pakettiin, päätyvät julkisiksi). Pidä se poissa myös URL-osoitteista, lokeista ja käyttäjille näytettävistä virheilmoituksista.
Pidä lisäksi voimassaoloaika mahdollisimman lyhyenä käytännön syistä. API-viitteiden mukaan expires_after.seconds on oletusarvoisesti 600 sekuntia ja enimmillään 3 600; dokumentaatiossa käytetään esimerkeissä arvoa 300. Kaiken kaikkiaan tunnisteen on oltava voimassa, kun asiakas avaa yhteyden. Lyhyt voimassaoloaika kutistaa aikaa, jonka aikana siepattu tunniste voidaan käyttää.
Dokumentaatio ei kerro, katkaiseeko vanhentunut tunniste jo auki olevan yhteyden. Jos asiakkaasi tarvitsee muodostaa yhteyden uudelleen verkkokatkon tai hyvin pitkän istunnon aikana, pyydä uusi tunniste ja käytä istunnon jatkamista (session resumption): ota käyttöön resumption.enabled kohdassa session.update, säilytä conversation.created:sta saamasi ID ja avaa WebSocket uudelleen parametrilla ?conversation_id=<id>. Edelliset vuorot toistetaan, ja malli jatkaa siitä, mihin se 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 } }, // lähetä uudelleen jokaisella yhteydellä
}));
return ws;
}
HTTP-tilassa toimivalle TTS:lle on olemassa vieläkin yksinkertaisempi vaihtoehto tunnisteille: välityspalvelin (proxy). Asiakas lähettää tekstinsä palvelinpuolellesi, palvelinpuolesi kutsuu TTS:ää ja palauttaa äänen. Avain ei koskaan poistu palvelimeltasi, ja saat luontevan paikan sisällön suodattamiselle ja käytön mittaamiselle matkan varrella.
Keskeiset asiat
- Väliaikaiset tunnisteet turvaavat pääsyn Voice Agentiin asiakaspuolen sovelluksista
POST /v1/realtime/client_secretspalauttaa arvotvaluejaexpires_at;expires_after.secondson oletusarvoisesti 600 ja enimmillään 3 600- Selaimessa tunniste sijoitetaan aliprotokollaan
xai-client-secret.<token> - Palvelinpuolesi on tarkistettava tunnistautuminen ja käyttöoikeudet ennen tunnisteen luomista
- Älä koskaan paljasta API-avaintasi asiakaspuolella, URL-osoitteissa tai lokeissa
- HTTP-TTS:n kohdalla välityspalvelimen käyttö palvelinpuolella on kelvollinen vaihtoehto väliaikaisille tunnisteille