Pereiti prie pagrindinio turinio
Lietuvių— Pasirinkite kalbą
Meniu

Autentifikavimas ir laikinieji žetonai

Paskaita 2 iš 16 Atnaujinta 2026 m. liepos 30 d. Kūrėjas
Šiame puslapyje
  1. Du autentifikavimo būdai
  2. Rekomenduojama architektūra su laikinaisiais žetonais
  3. Saugumo geriausios praktikos
  4. Svarbiausi punktai

Du autentifikavimo būdai

Voice Agent API siūlo du būdus autentifikuoti savo WebSocket ryšį. Kurį pasirinkti, priklauso nuo to, kur veikia tavo kodas: serveryje ar kliento pusėje.

Tiesioginis API raktas (serverio pusė)

Paprastiausias būdas – perduoti savo API raktą „Authorization“ antraštėje atidarant WebSocket. Tai tinka serverio programoms, kur raktas lieka apsaugotas:

const ws = new WebSocket("wss://api.x.ai/v1/realtime", {
  headers: {
    "Authorization": "Bearer xai-your-api-key"
  }
});

Niekada nenaudok šio metodo kode, kuris vykdoma naršyklėje: API raktas būtų atskleistas源代码 arba kūrėjo įrankiuose.

Laikinieji žetonai (kliento pusė)

Front-end programoms (naršyklė, mobiliosios) xAI suteikia laikinuosius žetonus. Tavo backendas sugeneruoja trumpalaikį žetoną, kurį tada perduodi klientui WebSocket ryšiui užmegzti.

Žetoną sukuri siųsdami POST užklausą:

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}}'

Laukas expires_after.seconds nustato, kiek sekundžių žetonas galioja. Oficialioje dokumentacijoje pateiktame pavyzdyje naudojama 300 sekundžių (5 minutės): laikinasis žetonas skirtas padengti balso sesiją, o ne egzistuoti ilgai. Siek kuo trumpesnio galiojimo laiko, kuris tinka tavo sesijoms.

Rekomenduojama architektūra su laikinaisiais žetonais

Štai visas srautas žiniatinklio programai:

// 1. Serverio pusė (Node.js/Express): sugeneruoti žetoną
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 } })
    }
  );
  // Grąžinti xAI atsakymo kūną tokį, koks yra;
  // jame yra laikinasis žetonas
  res.json(await response.json());
});

// 2. Kliento pusė (naršyklė): naudoti žetoną
// Naršyklės WebSocket konstruktorius nepriima antraščių:
// žetonas perduodamas kaip SUBPROTOCOL, priešdėlis „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");
  };
}

Žetonų atnaujinimas

Dokumentacijoje nenurodyta, ar baigiantis žetono galiojimui uždaromas jau atidarytas ryšys. Bet kuriuo atveju tavo programa turi turėti planą ryšiui nutrūkus: stebėk uždarymo įvykį, paprašyk backendo naujo žetono ir prisijunk iš naujo:

ws.onclose = async () => {
  // Ryšys nutrūko arba uždarytas: prašyti naujo žetono
  const newToken = await fetchNewToken();
  reconnect(newToken);
};

Saugumo geriausios praktikos

Keletas esminių taisyklių užtikrins tavo ryšių saugumą:

  • Niekada neatskleisk savo pagrindinio API rakto kliento pusėje
  • Laikyk galiojimo laiką (expires_after.seconds) kuo trumpesnį: jei vidutinė sesija trunka penkias minutes, pakanka 300–600 sekundžių
  • Tikrink žetonų užklausas serveryje (vartotojo autentifikavimas, užklausų ribojimas)
  • Registruok žetonų kūrimą, kad galėtum pastebėti neįprastą naudojimą
  • Pakeisk savo pagrindinį API raktą, jei įtari, kad jis buvo pažeistas

Svarbiausi punktai

  • Tiesioginis API raktas tinka tik serverio programoms
  • Laikinieji žetonai yra būtini kliento pusės programoms (naršyklė, mobiliosios)
  • Nustatyk žetono galiojimo laiką naudodamas expires_after.seconds ir laikyk jį trumpą (oficialiame pavyzdyje – 300 sekundžių)
  • Rekomenduojamas srautas: tavo backendas sugeneruoja žetoną, o front-endas jį perduoda kaip xai-client-secret. subprotokolą WebSocket ryšiui užmegzti
  • Visada numatyk automatinį žetonų atnaujinimą