Salt la conținutul principal
Română— Alege o limbă
Meniu

Autentificare prin token Bearer

Lecția 14 din 14 Actualizată 30 iulie 2026 Dezvoltator
Pe această pagină
  1. Securizați apelurile API
  2. Schema token Bearer
  3. Erori de autentificare
  4. Cele mai bune practici de securitate
  5. Detectarea scurgerilor
  6. HTTPS obligatoriu
  7. Puncte cheie
  8. Verificați-vă cunoștințele

Securizați apelurile API

Ghid de început în documentația xAI 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_KEY este 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:

  1. Creați o nouă cheie în consola xAI
  2. Actualizați cheia în seiful de secrete
  3. Redeploiați aplicația
  4. Verificați dacă totul funcționează cu noua cheie
  5. 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:

  1. Revocați-o imediat în consola xAI
  2. Verificați istoricul de utilizare pentru activitate frauduloasă
  3. Creați o nouă cheie
  4. 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.