Aqbeż għall-kontenut ewlieni
Malti— Agħżel lingwa
Menu

Tokens effimeri u sigurtà

Lezzjoni 13 / 14 Aġġornat 3 ta’ Novembru 2026 Livell Medju
F'din il-paġna
  1. Il-problema biċ-ċavetta tal-API fuq il-klijent
  2. Kif taħdem
  3. L-arkitettura end-to-end
  4. Regoli li qatt m’għandek tikser
  5. Punti Ewlenin

Aġġornat fit-3 ta’ Novembru 2026, ibbażat fuq ir-referenza tal-API tal-Vuċi ta’ xAI. Sorsi: Tokens Effimeri · Referenza tal-API tal-Vuċi · Riprensjoni tas-Sessjoni.

Il-problema biċ-ċavetta tal-API fuq il-klijent

Applikazzjoni tal-vuċi li taħdem f’browser jew fuq telefon ma tistax tiċċaqlaq biċ-ċavetta tal-API tiegħek. Kwalunkwe viżitatur jista’ jiftaħ l-għodod tal-iżviluppatur, jaqra ċ-ċavetta mill-pakkett JavaScript jew minn header ta’ talba, u mbagħad jużaha fuq il-kont tiegħek sakemm il-kwota tiegħek tintemm. L-ebda ammont ta’ obfuskar ma jipproteġi valur li l-klijent irid ikollu biex isejaħ l-API.

It-tweġiba ta’ xAI hija t-tokens effimeri, imsejħa wkoll sigrieti tal-klijent: token għal żmien qasir, iġġenerat mis-server tiegħek, li jawtorizza sessjoni tal-vuċi u xejn aktar.

600s
ħajja medja
3600s
ħajja massima
POST
/v1/realtime/client_secrets
valur
it-token, b'expires_at

Kif taħdem

Il-fluss jinżel għal ħames passi:

  1. Il-backend tiegħek (server sigur) isejjaħ POST /v1/realtime/client_secrets biċ-ċavetta tal-API tiegħek
  2. L-API tirritorna token temporanju b’ħajja limitata
  3. Il-backend tiegħek jibgħat dak it-token lill-klijent (browser jew app mobbli)
  4. Il-klijent juża t-token biex jikkonnettja mal-WebSocket tal-Aġent tal-Vuċi
  5. It-token jiskadi wara l-ħajja li għażilt int (expires_after.seconds)

X’jista’ jitnixxa fuq in-naħa tal-klijent issa jiswa ferm inqas: token li jiskadi fi żmien minuti u li jista’ jiftaħ biss sessjoni tal-vuċi, mhux iċ-ċavetta tal-API tiegħek. Fuq is-server, il-ġenerazzjoni tiegħu tieħu ftit linji ta’ kodiċi. Innota li l-handler jibda billi jiċċekkja l-utent: mingħajr dik il-verifika, il-backend tiegħek ikun sempliċiment distributur pubbliku ta’ tokens.

// Node.js backend (Express)
app.post("/api/voice-token", async (req, res) => {
  // Iċċekkja li l-utent huwa awtentikat
  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 minuti, id-default
      })
    }
  );

  const data = await response.json();  // { value, expires_at }
  res.json({ token: data.value, expiresAt: data.expires_at });
});

Il-klijent jaf biss bir-rotta tiegħek stess: jitlob token, imbagħad jiftaħ il-WebSocket bih.

// Frontend (browser)
async function startVoiceSession() {
  // Itlob token mill-backend
  const tokenRes = await fetch("/api/voice-token", { method: "POST" });
  const { token } = await tokenRes.json();

  // Il-WebSocket tal-browser ma jaċċettax headers:
  // it-token imur f'subprotocol, b'prefiss "xai-client-secret."
  const ws = new WebSocket(
    "wss://api.x.ai/v1/realtime?model=grok-voice-latest",
    [`xai-client-secret.${token}`]
  );

  // ... konfigurazzjoni tas-sessjoni
}

L-arkitettura end-to-end

Meta tgħaqqad kollox, il-fluss jibda bl-utent jidħol fl-app tiegħek. Il-klijent tiegħu mbagħad jitlob token tal-vuċi mill-backend tiegħek, u l-backend jiċċekkja l-awtentikazzjoni u l-permessi qabel ma jiġġenera t-token effimeru permezz tal-API ta’ xAI. It-token jivvjaġġa lura lejn il-klijent, li jużah biex jiftaħ is-sessjoni tal-Aġent tal-Vuċi, u jiskadi awtomatikament fi tmiem il-ħajja tiegħu.

Dik il-verifika bejn it-talba u l-ġenerazzjoni tbiddel relè sempliċi f’punt ta’ kontroll, u hemmhekk jgħixu r-regoli tan-negozju tiegħek. Tista’ tillimita n-numru ta’ sessjonijiet tal-vuċi għal kull utent kuljum, sabiex kont wieħed ma jkunx jista’ jħaraq il-baġit mensili tiegħek f’lejl waħda. Tista’ tirriżerva tokens għal abbonamenti attivi, u timponi l-mudell tan-negozju tiegħek f’post ieħor għajr l-interfaċċa. Tista’ tillimita r-rata tat-talbiet, sabiex klijent bi żball jew malizzjuż ma jkunx jista’ jitlob elf token fil-minuta. U tista’ tirreġistra kull token li tiġġenera: din hija l-unika bażi affidabbli tiegħek għall-monitoraġġ, il-fatturazzjoni interna, u l-analiżi tal-inċidenti.

Regoli li qatt m’għandek tikser

Iċ-ċavetta tal-API qatt ma tmur għand il-klijent, f’ebda forma. Żommha ‘l bogħod mill-JavaScript tal-front-end u ‘l bogħod minn kwalunkwe varjabbli tal-ambjent esposta għall-bini tal-browser (varjabbli b’prefiss biex jiġu injettati fil-pakkett jispiċċaw pubbliċi). Żommha ‘l bogħod mill-URLs, mil-logs, u mill-messaġġi ta’ żball murija lill-utenti wkoll.

Imbagħad, żomm il-ħajja kemm jista’ jkun qasira skont il-prattikabbiltà. Skont ir-referenza tal-API, expires_after.seconds għandu default ta’ 600 sekonda u jilħaq massimu ta’ 3,600; id-dokumentazzjoni tuża 300 fl-eżempji tagħha. Qabel kollox, it-token jeħtieġ li jkun validu meta l-klijent jiftaħ il-konnessjoni. Ħajja qasira tnaqqas it-tieqa li matulha token interċettat jista’ jintuża.

Id-dokumentazzjoni ma tgħidx jekk token li qed jiskadi jaqtax konnessjoni li diġà hija miftuħa. Jekk il-klijent tiegħek jeħtieġ li jerġa’ jikkonnettja, wara telfa fin-netwerk jew matul sessjoni twila ħafna, itlob token ġdid u uża r-riprensjoni tas-sessjoni: ippermetti resumption.enabled f’session.update, żomm l-ID li tirċievi f’conversation.created, imbagħad erġa’ ftaħ il-WebSocket b’?conversation_id=<id>. Id-dawriet preċedenti jerġgħu jintlagħbu, u l-mudell ikompli minn fejn waqaf.

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 } },  // ibgħat mill-ġdid fuq kull konnessjoni
  }));
  return ws;
}

Għat-TTS f’modalità HTTP, hemm alternattiva saħansitra aktar sempliċi għat-tokens: proxy. Il-klijent jibgħat it-test tiegħu lill-backend tiegħek, u l-backend tiegħek isejjaħ it-TTS u jirritorna l-awdjo. Iċ-ċavetta qatt ma toħroġ mis-server tiegħek, u tikseb post naturali biex tiffiltra l-kontenut u tkejjel l-użu matul it-triq.

Punti Ewlenin

  • It-tokens effimeri jissiguraw l-aċċess għall-Aġent tal-Vuċi minn apps fuq in-naħa tal-klijent
  • POST /v1/realtime/client_secrets jirritorna value u expires_at; expires_after.seconds għandu default ta’ 600 u jilħaq massimu ta’ 3,600
  • Fil-browser, it-token imur fis-subprotocol xai-client-secret.<token>
  • Il-backend tiegħek irid jiċċekkja l-awtentikazzjoni u l-permessi qabel ma jiġġenera token
  • Qatt tesponi ċ-ċavetta tal-API tiegħek fuq il-klijent, fl-URLs, jew fil-logs
  • Għat-TTS HTTP, l-użu ta’ proxy permezz tal-backend tiegħek huwa alternattiva valida għat-tokens effimeri