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

Tokens Effimeri għal Konnessjonijiet WebSocket

Lezzjoni 5 / 12 Aġġornat 28 ta’ Lulju 2026 Avvanzat
F'din il-paġna
  1. Il-problema: awtentikazzjoni ta’ klijent mingħajr ma tikxef iċ-ċavetta tiegħek
  2. Kif jaħdmu t-tokens effimeri
  3. L-għażla tad-durata t-tajba
  4. Implimentazzjoni tal-Backend
  5. Punti Ewlenin

Il-problema: awtentikazzjoni ta’ klijent mingħajr ma tikxef iċ-ċavetta tiegħek

Meta tibni applikazzjoni tal-vuċi jew f’ħin reali bl-API ta’ Grok, trid tistabbilixxi konnessjoni WebSocket direttament mill-browser jew mill-klijent mobbli. Ir-rotta tat-traffiku permezz tas-server tiegħek iżżid latenza li tkisser il-konversazzjoni fluwida tal-vuċi. Iżda l-konnessjonijiet diretti joħolqu problema ta’ awtentikazzjoni: qatt m’għandek tinkludi ċ-ċavetta tal-API tiegħek fil-kodiċi tan-naħa tal-klijent.

Ir-raġuni hija sempliċi: kwalunkwe ċavetta mħallta fil-JavaScript tal-frontend, f’applikazzjoni mobbli li tista’ tiġi dekkompilata, jew f’binarju distribwit, tiġi kompromessa hekk kif tippubblikaha. Kwalunkwe utent jista’ jiftaħ l-għodod tal-iżviluppatur tal-browser tiegħu u jaqraha. Biex issolvi dan, xAI toffri tokens effimeri: tokens temporanji li l-klijenti jistgħu jużaw mingħajr qatt ma jaraw iċ-ċavetta prinċipali.

600s
Durata default
3600s
Durata massima
POST
/v1/realtime/client_secrets
Bearer
Token temporanju

Kif jaħdmu t-tokens effimeri

L-arkitettura ssegwi prinċipju wieħed: iċ-ċavetta tal-API qatt ma titlaq is-server tiegħek, u l-klijent jirċievi biss token għal żmien qasir. Il-fluss huwa qasir. Il-klijent jitlob token mill-backend tiegħek, li jsejjaħ POST /v1/realtime/client_secrets biċ-ċavetta tal-API tiegħek. Din is-sejħa hija l-uniku post fejn tidher iċ-ċavetta, u dan iseħħ kompletament fuq in-naħa tas-server. xAI jirritorna token effimeru bid-data ta’ skadenza tiegħu, li l-backend tiegħek jgħaddi lill-klijent. Imbagħad il-klijent jiftaħ il-konnessjoni WebSocket ma’ wss://api.x.ai/v1/realtime u jippreżenta dan it-token. F’ebda mument il-browser ma jara ċ-ċavetta prinċipali; dan jittratta token li jiskadi waħdu.

Is-sejħa tal-ħolqien mill-backend tiegħek tidher hekk:

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": 600}}'

U r-rispons:

{
  "value": "Bearer eyJhbGciOiJSUzI1NiIs...",
  "expires_at": 1712001200
}

Fir-rigward tad-durata, għandek tliet punti ta’ referenza: m’hemm l-ebda limitu minimu dokumentat (ftit sekondi huma possibbli), il-valur default huwa 600 sekonda (10 minuti), u l-massimu huwa 3600 sekonda (siegħa).

L-għażla tad-durata t-tajba

Id-durata tat-token trid taqbel mal-każ tal-użu tiegħek, u din l-għażla hija deċiżjoni reali ta’ sigurtà. Għal interazzjonijiet sporadiċi tal-vuċi—mistoqsija u tweġiba, kumand bil-vuċi, dettatura—tieqa ta’ 300 sa 600 sekonda hija biżżejjed: is-sessjoni tintemm sew qabel l-iskadenza. Għal konversazzjonijiet sostenuti tal-vuċi bħal appoġġ lill-klijenti, intervista, jew laqgħa assistita, immira għal 600 sa 1800 sekonda biex tevita li titqatta’ f’nofs il-konversazzjoni. Sessjonijiet ta’ xogħol fit-tul—traskrizzjoni f’ħin reali, monitoraġġ kontinwu tal-vuċi—jistgħu jiġġustifikaw 1800 sa 3600 sekonda, iżda uża d-durata massima b’kawtela: din tespandi t-tieqa ta’ sfruttament jekk it-token jiġi misruq.

Ir-regola tad-deheb tiġbor dan hekk: agħżel dejjem l-iqsar durata kompatibbli mal-każ tal-użu tiegħek. Jekk token jiġi interċettat, skadenza ta’ għaxar minuti tbiddel inċident potenzjalment serju f’fastidju żgħir.

Implimentazzjoni tal-Backend

Hawnhekk hemm eżempju ta’ proxy sigur f’Node.js:

// Rotta tal-Backend - TIPPROĊESSAX fuq in-naħa tal-klijent
app.post("/api/realtime-token", authenticateUser, 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 }
      })
    }
  );

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

Tliet dettalji f’dan l-eżempju iġorru s-sigurtà kollha tal-installazzjoni. Iċ-ċavetta tal-API tgħix f’varjabbli tal-ambjent tas-server, qatt fil-kodiċi. Il-middleware authenticateUser jivverifika l-identità tal-utent qabel ma joħroġ token—mingħajru, kulħadd jista’ jikseb tokens u jikkonsma l-kwota tiegħek fuq spejjeżek. U biss it-token effimeru, qatt iċ-ċavetta, jiġi rritornat lill-klijent.

Xi trapoli joħorġu regolarment fir-reviżjonijiet tal-kodiċi. Iċ-ċavetta tal-API tiżloq fil-frontend “biss għall-prototip” u tispiċċa inevitabbilment fil-produzzjoni. It-token maħluq sistematikament bid-durata massima, għall-konvenjenza, meta l-każ tal-użu jeħtieġ kwart minn hekk. L-endpoint tal-ġenerazzjoni mħalli mingħajr verifika ta’ awtentikazzjoni, miftuħ għal kulħadd. U n-nuqqas ta’ ġestjoni tat-tiġdid fuq in-naħa tal-klijent, li jipproduċi żbalji ta’ skadenza f’nofs is-sessjoni minflok konnessjoni mill-ġdid trasparenti: peress li r-rispons jagħtik expires_at, il-klijent tiegħek għandu kollox meħtieġ biex jitlob token ġdid qabel l-iskadenza minflok wara.

Punti Ewlenin

  • It-tokens effimeri jippermettu awtentikazzjoni WebSocket mingħajr ma tikxef iċ-ċavetta tal-API tiegħek
  • Endpoint: POST /v1/realtime/client_secrets (sejħa fuq in-naħa tas-server biss)
  • Durata konfigurabbli minn ftit sekondi sa massimu ta’ 3600 sekonda (default: 600s)
  • Il-backend tiegħek jaġixxi bħala proxy ta’ awtentikazzjoni bejn il-klijent u xAI
  • Agħżel dejjem l-iqsar durata kompatibbli mal-użu tiegħek