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

Awtentikazzjoni u tokens effimeri

Lezzjoni 2 / 16 Aġġornat 30 ta’ Lulju 2026 Zviluppatur
F'din il-paġna
  1. Żewġ modi biex tawtentika ruħek
  2. Arkitettura rakkomandata b’tokens effimeri
  3. L-aħjar prattiki ta’ sigurtà
  4. Punti Ewlenin

Żewġ modi biex tawtentika ruħek

L-API tal-Aġent Vuċi (Voice Agent API) toffri żewġ metodi biex tawtentika l-konnessjoni WebSocket tiegħek. Il-metodu li tagħżel jiddependi minn fejn qed jiġi eżegwit il-kodiċi tiegħek: fuq is-server jew fuq il-klijent.

Ċavetta API diretta (naħa tas-server)

L-aktar metodu sempliċi huwa li tgħaddi ċ-ċavetta API tiegħek fl-intestazzjoni ta’ awtorizzazzjoni meta tiftaħ il-WebSocket. Dan jaħdem għal applikazzjonijiet tas-server, fejn iċ-ċavetta tibqa’ protetta:

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

Qatt tuża dan il-metodu f’kodiċi li jiġi eżegwit fil-browser: iċ-ċavetta API tkun esposta fis-sors tal-kodiċi jew fl-għodod tal-iżviluppatur.

Tokens effimeri (naħa tal-klijent)

Għal applikazzjonijiet front-end (browser, mobbli), xAI jipprovdi tokens effimeri. Il-backend tiegħek jiġġenera token għal żmien qasir, li mbagħad tgħaddih lill-klijent biex jiftaħ il-konnessjoni WebSocket.

Toħloq token b’talba POST:

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

Il-kamp expires_after.seconds jistabbilixxi kemm-il sekonda jibqa’ validu t-token. L-eżempju fid-dokumentazzjoni uffiċjali juża 300 sekonda (5 minuti): token effimeru huwa maħsub biex ikopri sessjoni vuċi, mhux biex idum. Immira għall-iqsar ħajja possibbli li taħdem għas-sessjonijiet tiegħek.

Arkitettura rakkomandata b’tokens effimeri

Hawnhekk hemm il-fluss sħiħ għal applikazzjoni web:

// 1. Naħa tas-server (Node.js/Express): iġġenera t-token
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 } })
    }
  );
  // Irritorna l-korp tar-risposta ta' xAI kif inhu;
  // fih it-token effimeru
  res.json(await response.json());
});

// 2. Naħa tal-klijent (browser): uża t-token
// Il-kostruttur WebSocket tal-browser ma jaċċettax intestazzjonijiet:
// it-token jgħaddi bħala SUBPROTOCOL, b'prefiss "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");
  };
}

Tiġdid tat-tokens

Id-dokumentazzjoni ma tgħidx jekk token li qed jiskadi jagħlaqx konnessjoni li diġà hija miftuħa. Fi kwalunkwe każ, l-app tiegħek trid tkun ippreparata għal meta tinqata’ l-konnessjoni: osserva l-avveniment ta’ għeluq (close event), itlob token ġdid mill-backend tiegħek, imbagħad erġa’ għaqqad:

ws.onclose = async () => {
  // Konnessjoni mitlufa jew magħluqa: itlob token ġdid
  const newToken = await fetchNewToken();
  reconnect(newToken);
};

L-aħjar prattiki ta’ sigurtà

Xi ftit regoli essenzjali jżommu l-konnessjonijiet tiegħek sikuri:

  • Qatt tesponi ċ-ċavetta API prinċipali tiegħek fuq il-klijent
  • Żomm il-ħajja (expires_after.seconds) kemm jista’ jkun qasira: jekk is-sessjoni medja tiegħek ddum ħames minuti, bejn 300 u 600 sekonda huma biżżejjed
  • Ivvalida t-talbiet għat-tokens fuq is-server (awtentikazzjoni tal-utent, limitazzjoni tar-rata)
  • Irreġistra il-ħolqien tat-tokens biex tkun tista’ tidentifika użu anormali
  • Beddel iċ-ċavetta API prinċipali tiegħek jekk tissuspetta li ġiet kompromessa

Punti Ewlenin

  • Ċavetta API diretta hija xierqa biss għal applikazzjonijiet tas-server
  • Tokens effimeri huma obbligatorji għal applikazzjonijiet fuq in-naħa tal-klijent (browser, mobbli)
  • Iddetermina l-ħajja tat-token b’expires_after.seconds u żommha qasira (300 sekonda fl-eżempju uffiċjali)
  • Il-fluss rakkomandat: il-backend tiegħek jiġġenera t-token, u l-front end tiegħek jgħaddih bħala s-sottoprotokoll xai-client-secret. biex jiftaħ il-WebSocket
  • Ippjana dejjem għat-tiġdid awtomatiku tat-tokens