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

Todentaminen ja kertakäyttöiset tunnisteet

Oppitunti 2 / 16 Päivitetty 30. heinäkuuta 2026 Kehittäjä
Tällä sivulla
  1. Kaksi todennustapaa
  2. Suositeltu arkkitehtuuri kertakäyttöisillä tunnisteilla
  3. Turvallisuuden parhaat käytännöt
  4. Keskeiset asiat

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.seconds ja 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