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

Crearea și configurarea unei chei API

Lecția 2 din 14 Actualizată 29 iulie 2026 Dezvoltator
Pe această pagină
  1. De ce să creați chei prin API
  2. Endpoint de creare
  3. Exemplu complet cu curl
  4. Strategii ACL recomandate
  5. Endpoint-uri ACL disponibile
  6. Puncte cheie

De ce să creați chei prin API

Crearea manuală a unei chei durează treizeci de secunde—ceea ce este exact motivul pentru care aveți nevoie de automatizare. Fiind rapidă, o faceți fără să gândiți: nicio convenție de denumire, nicio limită de rată, doar un wildcard „pentru a merge repede“. Șase luni mai târziu, nimeni nu mai știe ce face fiecare cheie.

Utilizarea API-ului vă obligă să denumiți, să definiți domeniul de aplicare și să limitați fiecare cheie, deoarece acestea sunt parametri de script. Coerența încetează să mai fie o disciplină pe care trebuie să o mențineți și devine o proprietate a codului. Puteți automatiza crearea cheilor pentru mediile dumneavoastră (dev, staging, production), puteți aplica ACL-uri granulare și puteți defini limite de rată—toate acestea direct în scripturile de deploy sau în instrumentele de infrastructură.

Endpoint de creare

Pentru a crea o cheie API, trimiteți o cerere POST la următorul endpoint:

POST /auth/teams/{teamId}/api-keys

Corpul cererii

{
  "name": "ma-cle-production",
  "acls": [
    "api-key:endpoint:chat",
    "api-key:model:grok-4.20-0309-reasoning"
  ],
  "qps": 10,
  "qpm": 100,
  "tpm": 1000000,
  "expireTime": "2026-12-31T23:59:59Z"
}

Parametri detaliați

name (obligatoriu): un identificator lizibil pentru cheia dumneavoastră. Alegeți un nume descriptiv care indică utilizarea (prod-backend, staging-chatbot, dev-john). Acest nume apare în consolă și în jurnalele de utilizare.

acls (obligatoriu): lista de permisiuni acordate acestei chei. Sunt disponibile două formate:

  • api-key:endpoint:[endpoint] — restricționează endpoint-urile accesibile (chat, embed, image, models, sample, tokenize, documents)
  • api-key:model:[model] — restricționează modelele utilizabile (grok-4.20-0309-reasoning, grok-4.3, etc.)

Caracterul * funcționează ca un wildcard: api-key:endpoint:* autorizează toate endpoint-urile, api-key:model:* toate modelele. Rezervați această opțiune pentru dezvoltarea locală. În producție, un wildcard înseamnă că o cheie compromisă oferă acces la tot ce poate face echipa dumneavoastră—inclusiv la cele mai costisitoare modele, pe care aplicația dumneavoastră s-ar pute să nu le folosească niciodată.

qps (opțional): interogări pe secundă — numărul maxim de cereri pe secundă.

qpm (opțional): interogări pe minut — numărul maxim de cereri pe minut.

tpm (opțional): tokeni pe minut — numărul maxim de tokeni procesați pe minut.

expireTime (opțional): data de expirare în format ISO 8601. Cheia va fi dezactivată automat la această dată.

Exemplu complet cu curl

curl -X POST "https://management-api.x.ai/auth/teams/$TEAM_ID/api-keys" \
  -H "Authorization: Bearer $MANAGEMENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "prod-backend-v2",
    "acls": [
      "api-key:endpoint:chat",
      "api-key:endpoint:embed",
      "api-key:model:grok-4.20-0309-reasoning",
      "api-key:model:grok-4.3"
    ],
    "qps": 20,
    "qpm": 500,
    "tpm": 2000000,
    "expireTime": "2027-06-30T23:59:59Z"
  }'

Răspunsul conține cheia secretă, care nu va mai fi afișată niciodată. Această regulă are o consecință practică pe care trebuie să o anticipați înainte de a rula scriptul, nu după: dacă creați chei într-o buclă, stocarea trebuie să aibă loc în același timp. O cheie pierdută între creare și înregistrare nu poate fi recuperată—trebuie să o ștergeți și să o luați de la capăt. Scrieți-o într-un seif (Vault, AWS Secrets Manager), nu în ieșirea standard a terminalului, unde va ajunge în istoricul dumneavoastră.

Strategii ACL recomandate

Cheie de dezvoltare (largă)

{
  "acls": ["api-key:endpoint:*", "api-key:model:*"],
  "qps": 5,
  "qpm": 50
}

Ideală pentru dezvoltarea locală: accesul este larg deoarece nu știți dinainte ce veți încerca, dar limitele de rată rămân scăzute. Acesta este compromisul corect—o buclă infinită scrisă din greșeală într-o vineri seară va costa câțiva cenți în loc de câteva sute de euro.

Cheie de producție (restricționată)

{
  "acls": [
    "api-key:endpoint:chat",
    "api-key:model:grok-4.20-0309-reasoning"
  ],
  "qps": 50,
  "qpm": 2000,
  "tpm": 5000000
}

În producție, regula se inversează: porniți de la ceea ce face efectiv aplicația și autorizați doar atât. Întrebarea de pus atunci când scrieți ACL-ul este întotdeauna aceeași—dacă această cheie scapă mâine, ce poate face un terț cu ea? O cheie limitată la chat pe un singur model și limitată la zece cereri pe secundă oferă un răspuns scurt.

Cheie temporară (expirabilă)

{
  "acls": ["api-key:endpoint:*", "api-key:model:*"],
  "expireTime": "2026-04-10T00:00:00Z"
}

Expirarea automată rezolvă problema pe care nimeni nu o gestionează: cheile pe care oamenii uită să le șteargă. Un POC, o demonstrație, un contractor temporar—in toate aceste cazuri, expireTime garantează că accesul se dezactivează singur. Aceasta este singura modalitate fiabilă de a menține un inventar curat, deoarece nu se bazează pe memoria nimănui.

Endpoint-uri ACL disponibile

Pentru a vedea endpoint-urile pe care le puteți utiliza în ACL-uri, consultați:

GET /auth/teams/{teamId}/endpoints

Endpoint-urile disponibile sunt: chat, embed, image, models, sample, tokenize, documents. Această listă poate evolua în timp, așa că verificați-o periodic.

Puncte cheie

  • Crearea cheilor se face prin POST /auth/teams/{teamId}/api-keys
  • ACL-urile urmează formatul api-key:endpoint:[nume] sau api-key:model:[nume]
  • Wildcard-ul * acordă acces complet la toate endpoint-urile sau modelele
  • Cheia secretă este afișată o singură dată la creare—salvați-o imediat
  • Definiți întotdeauna limite de rată (qps, qpm, tpm) adaptate utilizării
  • Utilizați expireTime pentru cheile temporare