Avtentikacija z žetonom Bearer
Na tej strani
Zavaruj svoje klice API-ja
Vsaka zahteva, poslana API-ju xAI, mora biti avtenticirana. API uporablja shemo žetona Bearer, ki je razširjen standard za REST API-je. Ta lekcija pojasnjuje delovanje tega mehanizma in najboljše prakse za zaščito tvojih ključev v produkcijskem okolju.
Shema žetona Bearer
Kot ime nakazuje, ima dostop do API-ja vsakdo, ki poseduje („nosi”) žeton. Zato je zaščita tvojega ključa temeljnega pomena: poleg samega žetona ni nobene dodatne preverbe identitete.
Oblika glave
Vsaka zahteva HTTP mora vključevati glavo Authorization s predpono Bearer, ki ji sledi tvoj ključ:
Authorization: Bearer xai-your-api-key
Pri uporabi orodja cURL to izgleda takole:
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"}'
V Pythonu SDK-ji to glavo samodejno obravnavajo, ko ključ posreduješ konstruktorju odjemalca.
Napake pri avtentikaciji
HTTP 401 Unauthorized
Ta napaka pomeni, da tvoj ključ manjka, je neveljaven ali preklican. Preveri:
- Ali je spremenljivka okolja
XAI_API_KEYnastavljena - Ali se ključ začne z
xai- - Ali ključ ni bil preklican v konzoli
HTTP 403 Forbidden
Tvoj ključ je veljaven, vendar nima dovoljenj, potrebnih za zahtevano dejanje. Do tega lahko pride zaradi omejitev ekipe za določene operacije.
Najboljše varnostne prakse
Ključa nikoli ne izpostavljaj v kodi
Ključi se nikoli ne smejo pojavljati v čistem besedilu v:
- Izvorni kodi z nadzorom različic (Git)
- Dnevnikih aplikacije (logih)
- URL-jih ali parametrih poizvedbe
- Sporočilih o napakah, prikazanih uporabnikom
- Težavah (issues) in zahtevkih za združitev (pull requests) na GitHubu
Uporabi trezor za skrivnosti
V produkcijskem okolju shrani svoje ključe v namenski sistem:
- AWS Secrets Manager ali Parameter Store
- Google Secret Manager
- Azure Key Vault
- HashiCorp Vault
- Skrivnosti tvoje platforme CI/CD (GitHub Actions, GitLab CI)
Vrtenje ključev
Ključe redno menjaj in to stori takoj, če sumiš na uhajanje:
- Ustvari nov ključ v konzoli xAI
- Posodobi ključ v svojem trezorju za skrivnosti
- Ponovno uvedi svojo aplikacijo
- Preveri, ali vse deluje z novim ključem
- Prekliči stari ključ v konzoli
Omeji dovoljenja
Če delaš v ekipi, ustvari ločene ključe za vsako storitev in okolje. Če je eden ogrožen, ostane vpliv omejen na en sam kontekst.
Zaznavanje uhajanj
Predpona xai- omogoča orodjem za zaznavanje (skeniranje skrivnosti GitHub, GitGuardian, TruffleHog), da samodejno identificirajo ključe v izvorni kodi. Ta orodja vklopi v svojih repozitorijih, da boš takoj opozorjen v primeru nenamernega razkritja.
Če je ključ zaznan v javni zavezi (commit):
- Takoj ga prekliči v konzoli xAI
- Preveri svojo zgodovino uporabe zaradi morebitne zlorabe
- Ustvari nov ključ
- Počisti zgodovino Gita (ali še bolje, obravnavaj ključ kot ogrožen in nadaljuj)
Zahtevan HTTPS
API xAI sprejema le povezave HTTPS. TLS šifrira tvoje zahteve med prenosom, vključno z glavo Authorization. Nikoli ne poskušaj obiti te zaščite: zahteva prek nešifriranega HTTP bi razkrila tvoj ključ v omrežju.
Ključne ugotovitve
- API uporablja shemo žetona Bearer prek glave
Authorization - Ključ je edini dejavnik avtentikacije: varuj ga kot geslo
- V produkcijskem okolju uporabi trezor za skrivnosti in nikoli ne vgrajuj ključa neposredno v kodo
- Vklopi zaznavanje uhajanj v svojih repozitorijih Git
- Redno menjaj ključe in takoj prekliči vsak ogrožen ključ
Preveri svoje razumevanje
Osnove API-ja xAI: zadnji preizkus, preden začneš graditi.
1. Kaj moraš storiti s ključem API-ja takoj, ko ga ustvariš?
Odgovor: Shrani ga na varno mesto (prikazan je le enkrat), izpostavi ga prek spremenljivke XAI_API_KEY namesto vgrajevanja v kodo, uporabi en ključ na okolje in ga takoj preizkusi s klicem na /v1/models.
2. Kaj je osnovni URL in zakaj je tako pomemben?
Odgovor: https://api.x.ai/v1. Omogoča združljivost z OpenAI: sprememba base_url in ključa zadostujeta, da obstoječo kodo OpenAI usmeriš na Grok.
3. Katere SDK-je lahko uporabljaš z Grokom?
Odgovor: Domači SDK xAI, SDK OpenAI (z osnovnim URL-jem xAI) in SDK Vercel AI na strani JavaScript, poleg cURL za testiranje: ekosistem je odprt.
4. Katera je glavna končna točka za generiranje?
Odgovor: POST /v1/responses, sodobna oblika; chat/completions ostaja na voljo kot dedna možnost za združljivost.
5. Kako je avtenticirana vsaka zahteva?
Odgovor: Z glavo Authorization: Bearer in ključem xai-…: standardna shema žetona Bearer, enaka ne glede na SDK ali orodje.
Varen ključ, osnovni URL, izbira SDK-ja, Bearer povsod: temelj je postavljen in naslednji tečaji o API-ju gradijo na njem.