Väliaikaiset tunnisteet WebSocket-yhteyksiä varten
Tällä sivulla
Ongelma: asiakkaan todentaminen paljastamatta avaintasi
Kun rakennat ääni- tai reaaliaikasovellusta Grok API:n avulla, sinun on muodostettava WebSocket-yhteys suoraan selaimesta tai mobiililaitteelta. Liikenteen reitittäminen palvelimesi kautta lisää viivettä, joka rikkoo sujuvan äänikeskustelun. Suorat yhteydet luovat kuitenkin todennusongelman: sinun ei saa koskaan sisällyttää API-avaintasi asiakaspuolen koodiin.
Syy on yksinkertainen: mikä tahansa etupään JavaScriptiin, purettavaan mobiilisovellukseen tai jaettuun binääritiedostoon upotettu avain vaarantuu heti, kun julkaiset sen. Kuka tahansa käyttäjä voi avata selaimensa kehittäjätyökalut ja lukea avaimen. Ratkaisuna xAI tarjoaa väliaikaisia tunnisteita: tilapäisiä tunnisteita, joita asiakkaat voivat käyttää näkemättä koskaan pääavainta.
Miten väliaikaiset tunnisteet toimivat
Arkkitehtuuri noudattaa yhtä periaatetta: API-avain ei koskaan poistu palvelimeltasi, ja asiakas saa vain lyhytikäisen tunnisteen. Vuokaavio on lyhyt. Asiakas pyytää tunnistetta backendiltäsi, joka kutsuu osoitetta POST /v1/realtime/client_secrets käyttäen API-avaintasi. Tämä kutsu on ainoa paikka, jossa avain esiintyy, ja se tapahtuu kokonaan palvelinpuolella. xAI palauttaa väliaikaisen tunnisteen sen vanhenemispäivämäärineen, jonka backendisi välittää asiakkaalle. Asiakas muodostaa sitten WebSocket-yhteyden osoitteeseen wss://api.x.ai/v1/realtime esittäen tämän tunnisteen. Missään vaiheessa selain ei näe pääavainta; se käsittelee tunnistetta, joka vanhenee itsestään.
Backendisi luontikutsu näyttää tältä:
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": 600}}'
Ja vastaus:
{
"value": "Bearer eyJhbGciOiJSUzI1NiIs...",
"expires_at": 1712001200
}
Keston osalta sinulla on kolme vertailukohtaa: dokumentoitua alarajaa ei ole (muutama sekunti on mahdollinen), oletusarvo on 600 sekuntia (10 minuuttia) ja enimmäisarvo on 3600 sekuntia (1 tunti).
Oikean keston valinta
Tunnisteen keston on vastattava käyttötapaustasi, ja tämä valinta on todellinen turvallisuuspäätös. Satunnaisiin äänivuorovaikutuksiin – kuten kysymys-vastaus, äänikomento tai sanelu – 300–600 sekunnin ikkuna on enemmän kuin riittävä: istunto päättyy hyvin ennen vanhenemista. Pitkiin äänikeskusteluihin, kuten asiakastukeen, haastatteluun tai avustettuun kokoukseen, tavoittele 600–1800 sekuntia välttääksesi yhteyden katkeamisen keskellä keskustelua. Pitkät työskentelyjaksot – reaaliaikainen litterointi, jatkuva äänivalvonta – voivat perustella 1800–3600 sekunnin käytön, mutta käytä enimmäiskestoa harkiten: se laajentaa hyväksikäyttöikkunaa, jos tunnistetunnus varastetaan.
Kultainen sääntö tiivistyy näin: valitse aina lyhin mahdollinen kesto, joka sopii käyttötapaukseesi. Jos tunnistetunnus siepataan, kymmenen minuutin vanhenemisaika muuttaa potentiaalisesti vakavan tapahtuman pieneksi harmiksi.
Backend-toteutus
Tässä on esimerkki turvallisesta välityspalvelimesta Node.js:llä:
// Backend-reitti - ÄLÄ paljasta asiakaspuolelle
app.post("/api/realtime-token", authenticateUser, 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 }
})
}
);
const token = await response.json();
res.json({ token: token.value, expires_at: token.expires_at });
});
Tässä esimerkissä on kolme yksityiskohtaa, jotka kantavat koko asetelman turvallisuuden. API-avain sijaitsee palvelimen ympäristömuuttujassa, ei koskaan koodissa. authenticateUser-välivaihe varmentaa käyttäjän henkilöllisyyden ennen tunnisteen myöntämistä – ilman sitä kuka tahansa voisi hankkia tunnisteita ja kuluttaa kiintiösi kustannuksellasi. Ja vain väliaikainen tunnistetunnus, ei koskaan avain, palautetaan asiakkaalle.
Koodikatselmuksissa nousee säännöllisesti esiin muutama sudenkuoppa. API-avain lipsahtaa etupäähän “vain prototyyppiä varten” ja päätyy väistämättä tuotantoon. Tunniste luodaan systemaattisesti enimmäiskestolla mukavuuden vuoksi, vaikka käyttötapaus vaatisi vain neljänneksen siitä. Luontipäätejätetään ilman todennuksen varmistusta, avoimena kaikille. Ja uudistuskäsittelyn puuttuminen asiakaspuolella, mikä tuottaa vanhenemisvirheitä kesken istunnon läpinäkyvän uudelleenyhteyden sijaan: koska vastaus antaa sinulle expires_at-arvon, asiakkaallasi on kaikki tarvittava pyytääkseen uusi tunnistetunnus ennen määräaikaa eikä sen jälkeen.
Keskeiset asiat
- Väliaikaiset tunnisteet mahdollistavat WebSocket-todennuksen paljastamatta API-avaintasi
- Päätepiste:
POST /v1/realtime/client_secrets(vain palvelinpuolen kutsu) - Muokattava kesto muutamasta sekunnista aina 3600 sekuntiin saakka (oletus: 600 s)
- Backendisi toimii todennusvälittäjänä asiakkaan ja xAI:n välillä
- Valitse aina lyhin käyttöösi sopiva kesto