Ефемерни токени за WebSocket връзки
На тази страница
Проблемът: удостоверяване на клиент без разкриване на ключа
Когато изграждате гласово приложение или такова в реално време с Grok API, трябва да установите WebSocket връзка директно от браузъра или мобилния клиент. Пренасочването на трафика през Вашия сървър добавя латентност, която нарушава плавността на гласовия разговор. Директните връзки обаче създават проблем с удостоверяването: никога не трябва да включвате Вашия API ключ в кода на страната на клиента.
Причината е проста: всеки ключ, вграден във фронтенд JavaScript, декомпилируемо мобилно приложение или разпространяван двоичен файл, е компрометиран в момента на публикуването му. Всеки потребител може да отвори инструментите за разработчици в браузъра си и да го прочете. За решаване на този проблем xAI предлага ефемерни токени: временни токени, които клиентите могат да използват, без никога да виждат главния ключ.
Как работят ефемерните токени
Архитектурата следва един принцип: API ключът никога не напуска Вашия сървър, а клиентът получава само токен с кратък срок на валидност. Потокът е кратък. Клиентът иска токен от Вашия бекенд, който извиква POST /v1/realtime/client_secrets с Вашия API ключ. Това извикване е единственото място, където се появява ключът, и то се случва изцяло на страната на сървъра. xAI връща ефемерен токен с дата на изтичане, която Вашият бекенд предава на клиента. След това клиентът отваря WebSocket връзка към wss://api.x.ai/v1/realtime, представяйки този токен. В нито един момент браузърът не вижда главния ключ; той работи с токен, който изтича автоматично.
Извикването за създаване от Вашия бекенд изглежда така:
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}}'
И отговорът:
{
"value": "Bearer eyJhbGciOiJSUzI1NiIs...",
"expires_at": 1712001200
}
Що се отнася до продължителността, имате три ориентира: няма документиран минимум (възможни са няколко секунди), стойността по подразбиране е 600 секунди (10 минути), а максимумът е 3600 секунди (1 час).
Избор на подходяща продължителност
Продължителността на токена трябва да съответства на Вашия случай на употреба и този избор е истинско решение за сигурност. За спорадични гласови взаимодействия – въпроси и отговори, гласова команда, диктовка – прозорец от 300 до 600 секунди е напълно достатъчен: сесията ще приключи много преди изтичането на срока. За продължителни гласови разговори, като клиентска поддръжка, интервю или асистирана среща, се стремете към 600 до 1800 секунди, за да избегнете прекъсване по средата на разговора. Продължителни работни сесии – транскрипция в реално време, непрекъснат гласов мониторинг – могат да оправдаят 1800 до 3600 секунди, но използвайте максималната продължителност предпазливо: тя разширява прозореца за експлоатация, ако токенът бъде откраднат.
Златното правило се обобщава така: винаги избирайте най-кратката продължителност, съвместима с Вашия случай на употреба. Ако токен бъде прихванат, изтичане след десет минути превръща потенциално сериозен инцидент в незначително неудобство.
Имплементация на бекенда
Ето пример за сигурен прокси сървър на Node.js:
// Backend route - DO NOT expose client-side
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 });
});
Три детайла в този пример носят цялата сигурност на настройката. API ключът се съхранява в променлива на сървърната среда, никога в кода. Middleware функцията authenticateUser проверява самоличността на потребителя преди издаването на токен – без нея всеки би могъл да получава токени и да консумира Вашата квота за Ваша сметка. И само ефемерният токен, никога ключът, се връща на клиента.
Няколко често срещани грешки излизат наяве при прегледите на код. API ключът, промъкнат във фронтенда „само за прототипа“, неизменно попада в продукционната среда. Токенът се създава системно с максимална продължителност заради удобство, когато случаят на употреба изисква една четвърт от това. Крайната точка за генериране остава без проверка за удостоверяване, отворена за всички. И липсата на обработка на подновяването от страна на клиента, което води до грешки при изтичане на срока по средата на сесията вместо прозрачно прекъсване на връзката: тъй като отговорът Ви дава expires_at, Вашият клиент разполага с всичко необходимо, за да поиска нов токен преди крайния срок, а не след него.
Ключови изводи
- Ефемерните токени позволяват удостоверяване чрез WebSocket без разкриване на Вашия API ключ
- Крайна точка:
POST /v1/realtime/client_secrets(само извикване от страна на сървъра) - Конфигурируема продължителност от няколко секунди до максимум 3600 секунди (по подразбиране: 600s)
- Вашият бекенд действа като удостоверяващ прокси между клиента и xAI
- Винаги избирайте най-кратката продължителност, съвместима с Вашето използване