Pāriet uz galveno saturu
Latviešu— Izvēlēties valodu
Izvēlne

Autentifikācija un īslaicīgie pilnvarojumi

Nodarbība 2 no 16 Atjaunota 2026. gada 30. jūlijs Programmētājs
Šajā lapā
  1. Divi autentifikācijas veidi
  2. Ieteicamā arhitektūra ar īslaicīgajiem pilnvarojumiem
  3. Drošības labākā prakse
  4. Galvenās atziņas

Divi autentifikācijas veidi

Voice Agent API piedāvā divus veidus, kā autentificēt savu WebSocket savienojumu. Tas, kuru izvēlēsies, ir atkarīgs no tā, kur darbojas tavs kods: serverī vai klientā.

Tiešā API atslēga (servera puse)

Vienkāršākā metode ir norādīt savu API atslēgu autorizācijas galvenē (header), atverot WebSocket. Tas darbojas servera lietotnēm, kur atslēga paliek pasargāta:

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

Nekad neizmanto šo metodi kodā, kas darbojas pārlūkprogrammā: API atslēga tiktu atklāta pirmkodā vai izstrādātāja rīkos.

Īslaicīgie pilnvarojumi (klienta puse)

Priekšpuses lietotnēm (pārlūkprogramma, mobilās ierīces) xAI nodrošina īslaicīgos pilnvarojumus (ephemeral tokens). Tavs backend ģenerē īsu derīguma termiņu esošu pilnvarojumu, ko pēc tam nodod klientam, lai tas atvērtu WebSocket savienojumu.

Pilnvarojumu izveido, veicot POST pieprasījumu:

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

Lauks expires_after.seconds nosaka, cik ilgi pilnvarojums ir derīgs (sekundēs). Oficiālajā dokumentācijas piemērā izmantoti 300 sekundes (5 minūtes): īslaicīgs pilnvarojums ir paredzēts, lai segtu balss sesiju, nevis lai pastāvētu ilgstoši. Tiecies pēc īsākā iespējamā derīguma termiņa, kas atbilst tavām sesijām.

Ieteicamā arhitektūra ar īslaicīgajiem pilnvarojumiem

Lūk, pilns darbplūsmas apraksts tīmekļa lietotnei:

// 1. Servera puse (Node.js/Express): ģenerē pilnvarojumu
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 } })
    }
  );
  // Atgriež xAI atbildes ķermeni nemainītu;
  // tas satur īslaicīgo pilnvarojumu
  res.json(await response.json());
});

// 2. Klienta puse (pārlūkprogramma): izmanto pilnvarojumu
// Pārlūkprogrammas WebSocket konstruktors nepieņem galvenes:
// pilnvarojums tiek ievietots apakšprotokolā (SUBPROTOCOL) ar prefiksu "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");
  };
}

Pilnvarojumu atjaunošana

Dokumentācijā nav precizēts, vai beidzoties derīguma termiņam, tiek slēgts jau atvērts savienojums. Lai vai kā, tavai lietotnei ir jābūt plānam gadījumam, ja savienojums pārtrūkst: uzraugi aizvēršanas notikumu (close event), pieprasi jaunu pilnvarojumu savam backendam un tad veic atkārtotu savienojumu:

ws.onclose = async () => {
  // Savienojums zaudēts vai aizvērts: pieprasa jaunu pilnvarojumu
  const newToken = await fetchNewToken();
  reconnect(newToken);
};

Drošības labākā prakse

Daži būtiski noteikumi nodrošinās tavu savienojumu drošību:

  • Nekad neatklāj savu galveno API atslēgu klientam
  • Uzturi derīguma termiņu (expires_after.seconds) pēc iespējas īsāku: ja tava vidējā sesija ilgst piecas minūtes, pietiek ar 300 līdz 600 sekundēm
  • Validē pilnvarojumu pieprasījumus serverī (lietotāja autentifikācija, ātruma ierobežošana)
  • Reģistrē pilnvarojumu izveidi, lai spētu noteikt neparastu lietojumu
  • Rotē savu galveno API atslēgu, ja ir aizdomas par tās kompromitāciju

Galvenās atziņas

  • Tieša API atslēga ir piemērota tikai servera lietotnēm
  • Īslaicīgie pilnvarojumi ir obligāti klientu puses lietotnēm (pārlūkprogramma, mobilās ierīces)
  • Iestati pilnvarojuma derīguma termiņu ar expires_after.seconds un uzturi to īsu (oficiālajā piemērā – 300 sekundes)
  • Ieteicamā darbplūsma: tavs backend ģenerē pilnvarojumu, bet tava priekšpuse to nodod kā xai-client-secret. apakšprotokolu, lai atvērtu WebSocket
  • Vienmēr plāno automātisku pilnvarojumu atjaunošanu