Автентикация и ефемерни токени
На тази страница
Два начина за автентикация
API за гласов агент предлага два начина за автентикация на Вашата WebSocket връзка. Изборът зависи от това къде се изпълнява кодът Ви: на сървъра или на клиента.
Директен API ключ (страна на сървъра)
Най-простият метод е да предадете Вашия API ключ в заглавката за оторизация при отваряне на WebSocket връзката. Това работи за сървърни приложения, където ключът остава защитен:
const ws = new WebSocket("wss://api.x.ai/v1/realtime", {
headers: {
"Authorization": "Bearer xai-your-api-key"
}
});
Никога не използвайте този метод в код, който се изпълнява в браузъра: API ключът би бил изложен в изходния код или в инструментите за разработчици.
Ефемерни токени (страна на клиента)
За фронтенд приложения (браузър, мобилни устройства), xAI предоставя ефемерни токени. Вашият бекенд генерира токен с кратък срок на валидност, който след това предавате на клиента за отваряне на WebSocket връзката.
Създавате токен чрез 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}}'
Полето expires_after.seconds определя колко дълго е валиден токенът, в секунди. Примерът в официалната документация използва 300 секунди (5 минути): ефемерният токен е предназначен да покрие една гласова сесия, а не да бъде постоянен. Стремете се към най-краткия възможен срок на валидност, подходящ за Вашите сесии.
Препоръчителна архитектура с ефемерни токени
Ето пълния поток за уеб приложение:
// 1. Страна на сървъра (Node.js/Express): генериране на токена
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 } })
}
);
// Върнете тялото на отговора от xAI както е;
// то съдържа ефемерния токен
res.json(await response.json());
});
// 2. Страна на клиента (браузър): използване на токена
// Конструкторът на WebSocket в браузъра не приема заглавки:
// токенът се предава като SUBPROTOCOL, с префикс "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");
};
}
Подновяване на токени
Документацията не уточнява дали изтичащият токен затваря вече установена връзка. Във всеки случай, Вашето приложение трябва да има план за случаите, когато връзката прекъсне: следете събитието за затваряне, поискайте нов токен от бекенда си и се свържете отново:
ws.onclose = async () => {
// Връзката е загубена или затворена: поисквайте нов токен
const newToken = await fetchNewToken();
reconnect(newToken);
};
Най-добри практики за сигурност
Няколко основни правила гарантират сигурността на Вашите връзки:
- Никога не излагайте основния си API ключ на клиента
- Задайте възможно най-кратък срок на валидност (
expires_after.seconds): ако средната Ви сесия трае пет минути, 300 до 600 секунди са достатъчни - Валидирайте заявките за токени на сървъра (автентикация на потребителя, ограничаване на честотата)
- Регистрирайте създаването на токени, за да откривате необичайна употреба
- Ротирайте основния си API ключ, ако подозирате, че е компрометиран
Ключови изводи
- Директният API ключ е подходящ само за сървърни приложения
- Ефемерните токени са задължителни за приложения от страна на клиента (браузър, мобилни устройства)
- Задайте срока на валидност на токена чрез
expires_after.secondsи го поддържайте кратък (300 секунди в официалния пример) - Препоръчителният поток е: бекендът Ви генерира токена, а фронтендът го предава като подпротокол
xai-client-secret.за отваряне на WebSocket връзката - Винаги планирайте автоматично подновяване на токените