Autentificare prin token Bearer
Pe această pagină
Securizați apelurile API
Fiecare cerere trimisă către API-ul xAI trebuie autentificată. API-ul utilizează schema Bearer token, un standard larg adoptat pentru API-urile REST. Această lecție explică funcționarea mecanismului și cele mai bune practici pentru protejarea cheilor dumneavoastră în producție.
Schema token Bearer
După cum sugerează și numele, oricine deține („poartă“) tokenul poate accesa API-ul. De aceea, protejarea cheii este fundamentală: nu există nicio verificare a identității dincolo de tokenul însuși.
Formatul antetului
Fiecare cerere HTTP trebuie să includă antetul Authorization cu prefixul Bearer, urmat de cheia dumneavoastră:
Authorization: Bearer xai-your-api-key
Cu cURL, acest lucru se traduce prin:
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"}'
În Python, SDK-urile gestionează automat acest antet atunci când transmiteți cheia constructorului clientului.
Erori de autentificare
HTTP 401 Unauthorized
Această eroare indică faptul că cheia lipsește, este invalidă sau a fost revocată. Verificați:
- Dacă variabila de mediu
XAI_API_KEYeste setată - Dacă cheia începe cu
xai- - Dacă cheia nu a fost revocată în consolă
HTTP 403 Forbidden
Cheia dumneavoastră este validă, dar nu dispune de permisiunile necesare pentru acțiunea solicitată. Acest lucru se poate întâmpla din cauza restricțiilor de echipă asupra anumitor operațiuni.
Cele mai bune practici de securitate
Nu expuneți niciodată o cheie în cod
Cheile nu trebuie să apară niciodată în text clar în:
- Codul sursă versionat (Git)
- Jurnalele aplicației (logs)
- URL-uri sau parametri de interogare
- Mesajele de eroare afișate utilizatorilor
- Problemele (issues) și cererile de extragere (pull requests) de pe GitHub
Utilizați un seif pentru secrete
În producție, stocați-vă cheile într-un sistem dedicat:
- AWS Secrets Manager sau Parameter Store
- Google Secret Manager
- Azure Key Vault
- HashiCorp Vault
- Secretele platformei dumneavoastră CI/CD (GitHub Actions, GitLab CI)
Rotirea cheilor
Schimbați-vă cheile periodic și imediat dacă suspectați o scurgere:
- Creați o nouă cheie în consola xAI
- Actualizați cheia în seiful de secrete
- Redeploiați aplicația
- Verificați dacă totul funcționează cu noua cheie
- Revocați vechea cheie în consolă
Limitarea permisiunilor
Dacă lucrați în echipă, creați chei separate pentru fiecare serviciu și mediu. Dacă una este compromisă, impactul rămâne limitat la un singur context.
Detectarea scurgerilor
Prefixul xai- permite instrumentelor de detectare (scanarea secretelor GitHub, GitGuardian, TruffleHog) să identifice automat cheile în codul sursă. Activați aceste instrumente în depozitele dumneavoastră pentru a fi alertat imediat în cazul unei expuneri accidentale.
Dacă o cheie este detectată într-un commit public:
- Revocați-o imediat în consola xAI
- Verificați istoricul de utilizare pentru activitate frauduloasă
- Creați o nouă cheie
- Curățați istoricul Git (sau, mai bine, considerați cheia compromisă și mergeți mai departe)
HTTPS obligatoriu
API-ul xAI acceptă doar conexiuni HTTPS. TLS criptează cererile dumneavoastră în timpul transmiterii, inclusiv antetul Authorization. Nu încercați niciodată să ocoliți această protecție: o cerere prin HTTP necriptat ar expune cheia dumneavoastră în rețea.
Puncte cheie
- API-ul utilizează schema Bearer token prin antetul
Authorization - Cheia este singurul factor de autentificare: protejați-o ca pe o parolă
- Utilizați un seif pentru secrete în producție și nu codificați niciodată o cheie direct în cod
- Activați detectarea scurgerilor în depozitele dumneavoastră Git
- Rotiți cheile periodic și revocați imediat orice cheie compromisă
Verificați-vă cunoștințele
Fundațiile API-ului xAI: o ultimă verificare înainte de a construi.
1. Ce trebuie să faceți cu o cheie API imediat după ce o creați?
Răspuns: Stocați-o într-un loc sigur (este afișată o singură dată), expuneți-o prin variabila XAI_API_KEY în loc să o codificați direct, utilizați o cheie per mediu și testați-o imediat cu un apel către /v1/models.
2. Care este URL-ul de bază și de ce este atât de important?
Răspuns: https://api.x.ai/v1. Acesta este ceea ce face posibilă compatibilitatea cu OpenAI: modificarea base_url și a cheii este suficientă pentru a direcționa codul OpenAI existent către Grok.
3. Ce SDK-uri puteți utiliza cu Grok?
Răspuns: SDK-ul nativ xAI, SDK-ul OpenAI (cu base_url xAI) și SDK-ul Vercel AI pentru partea de JavaScript, plus cURL pentru testare: ecosistemul este deschis.
4. Care este endpoint-ul principal de generare?
Răspuns: POST /v1/responses, formatul modern; chat/completions rămâne disponibil ca opțiune legacy pentru compatibilitate.
5. Cum este autentificată fiecare cerere?
Răspuns: Prin antetul Authorization: Bearer și cheia xai-…: schema standard Bearer token, aceeași indiferent de SDK sau instrument.
O cheie securizată, URL-ul de bază, alegerea SDK-ului, Bearer peste tot: fundația este pusă, iar următoarele cursuri API se bazează pe aceasta.