Удостоверяване с Bearer токен
На тази страница
Защитете вашите API повиквания
Всяка заявка, изпратена към API на xAI, трябва да бъде удостоверявана. API използва схемата Bearer token, широко приет стандарт за REST API. Този урок обяснява как работи механизмът и най-добрите практики за защита на вашите ключове в производствена среда.
Схемата Bearer token
Както подсказва името, всеки, който притежава („носи“) токена, може да получи достъп до API. Затова защитата на вашия ключ е от основно значение: няма проверка на самоличността извън самия токен.
Формат на хедъра
Всяка HTTP заявка трябва да включва хедъра Authorization с префикса Bearer, последван от вашия ключ:
Authorization: Bearer xai-your-api-key
С cURL това изглежда така:
curl https://api.x.ai/v1/responses \
-H "Authorization: Bearer $XAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model": "grok-4.5", "input": "Hello"}'
В Python SDK библиотеките обработват този хедър автоматично, когато предадете ключа на конструктора на клиента.
Грешки при удостоверяване
HTTP 401 Unauthorized
Тази грешка означава, че вашият ключ липсва, е невалиден или е отменен. Проверете:
- Дали променливата на средата
XAI_API_KEYе зададена - Дали ключът започва с
xai- - Дали ключът не е бил отменен в конзолата
HTTP 403 Forbidden
Вашият ключ е валиден, но няма необходимите разрешения за исканото действие. Това може да се случи при ограничения в екипа за определени операции.
Най-добри практики за сигурност
Никога не излагайте ключ в кода
Ключовете никога не трябва да се появяват в чист текст в:
- Версиониран изходен код (Git)
- Логи на приложенията
- URL адреси или параметри на заявките
- Съобщения за грешки, показвани на потребителите
- Проблеми (issues) и заявки за сливане (pull requests) в GitHub
Използвайте хранилище за тайни
В производствена среда съхранявайте ключовете си в специализирана система:
- AWS Secrets Manager или Parameter Store
- Google Secret Manager
- Azure Key Vault
- HashiCorp Vault
- Тайните на вашата CI/CD платформа (GitHub Actions, GitLab CI)
Ротация на ключовете
Сменяйте ключовете си редовно и незабавно, ако подозирате изтичане:
- Създайте нов ключ в конзолата на xAI
- Актуализирайте ключа във вашето хранилище за тайни
- Разположете отново приложението си
- Проверете дали всичко работи с новия ключ
- Отменете стария ключ в конзолата
Ограничете разрешенията
Ако работите в екип, създавайте отделни ключове за всяка услуга и среда. Ако един бъде компрометиран, въздействието остава ограничено до един конкретен контекст.
Откриване на изтичане
Префиксът xai- позволява на инструментите за откриване (GitHub secret scanning, GitGuardian, TruffleHog) да идентифицират ключове в изходния код автоматично. Активирайте тези инструменти във вашите хранилища, за да бъдете предупредени незабавно в случай на случайно излагане.
Ако ключ бъде открит в публичен комит:
- Отменете го незабавно в конзолата на xAI
- Проверете историята на използването си за измамни действия
- Създайте нов ключ
- Почистете Git историята си (или по-добре, третирайте ключа като компрометиран и продължете напред)
HTTPS е задължителен
API на xAI приема само HTTPS връзки. TLS криптира вашите заявки по време на предаване, включително хедъра Authorization. Никога не се опитвайте да заобиколите тази защита: заявка през некриптиран HTTP би изложила вашия ключ в мрежата.
Ключови изводи
- API използва схемата Bearer token чрез хедъра
Authorization - Ключът е единственият фактор за удостоверяване: пазете го като парола
- Използвайте хранилище за тайни в производствена среда и никога не вграждайте ключ директно в кода
- Активирайте откриването на изтичане във вашите Git хранилища
- Ротирайте ключовете редовно и отменяйте незабавно всеки компрометиран ключ
Проверете знанията си
Основите на API на xAI: една последна проверка, преди да започнете изграждането.
1. Какво трябва да направите с API ключ веднага след като го създадете?
Отговор: Съхранете го на сигурно място (показва се само веднъж), изложете го чрез променливата XAI_API_KEY, вместо да го вграждате в кода, използвайте по един ключ за всяка среда и го тествайте веднага с повикване към /v1/models.
2. Какъв е основният URL и защо е толкова важен?
Отговор: https://api.x.ai/v1. Той прави възможна съвместимостта с OpenAI: промяната на base_url и ключа е достатъчна, за да насочите съществуващ код за OpenAI към Grok.
3. Кои SDK можете да използвате с Grok?
Отговор: Нативният xAI SDK, OpenAI SDK (с xAI base_url) и Vercel AI SDK от страна на JavaScript, плюс cURL за тестване: екосистемата е отворена.
4. Коя е основната крайна точка за генериране?
Отговор: POST /v1/responses, модерният формат; chat/completions остава наличен като остаряла опция за съвместимост.
5. Как се удостоверява всяка заявка?
Отговор: С хедъра Authorization: Bearer и ключа xai-…: стандартната схема Bearer token, еднаква независимо от SDK или инструмента.
Защитен ключ, основен URL, избор на SDK, Bearer навсякъде: основата е положена и следващите курсове за API градят върху нея.