Crearea și configurarea unei chei API
Pe această pagină
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]sauapi-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
expireTimepentru cheile temporare