Siirry pääsisältöön
Suomi— Valitse kieli
Valikko

Väliaikaiset tunnisteet ja tietoturva

Oppitunti 13 / 14 Päivitetty 3. marraskuuta 2026 Keskitasoinen
Tällä sivulla
  1. Ongelma: API-avain asiakaspuolella
  2. Miten se toimii
  3. End-to-end-arkkitehtuuri
  4. Säännöt, joita ei saa koskaan rikkoa
  5. Keskeiset asiat

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.

600s
oletusikä
3600s
enimmäisikä
POST
/v1/realtime/client_secrets
value
tunniste, mukana expires_at

Miten se toimii

Prosessi tiivistyy viiteen vaiheeseen:

  1. Palvelinpuolesi (turvallinen palvelin) kutsuu osoitetta POST /v1/realtime/client_secrets käyttäen API-avaintasi
  2. API palauttaa väliaikaisen tunnisteen, jolla on rajoitettu voimassaoloaika
  3. Palvelinpuolesi lähettää tämän tunnisteen asiakkaalle (selain tai mobiilisovellus)
  4. Asiakas käyttää tunnistetta muodostaakseen yhteyden Voice Agent WebSocketiin
  5. 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_secrets palauttaa arvot value ja expires_at; expires_after.seconds on 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