Awtentikazzjoni u tokens effimeri
F'din il-paġna
Ż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.secondsu ż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