Sarakstīt un modificēt savas atslēgas
Šajā lapā
Tavu API atslēgu inventārs
Laika gaitā tava komanda uzkrāj API atslēgas dažādām vidēm, projektiem un komandas biedriem. Pārvaldības API ļauj sarakstīt visas aktīvās atslēgas, filtrēt tās pēc atļaujām un mainīt to iestatījumus, nepārradot tās no jauna.
Atslēgu saraksts
Šis galapunkts ir sākumpunkts jebkurai piekļuves revīzijai, un tieši šeit tu bieži vien atklāj patieso inventāru: atslēgas, kas izveidotas testam pirms astoņiem mēnešiem, atslēgu bijušā komandas biedra vārdā, divas ražošanas atslēgas, kur neviens nezina, kura tiek izmantota. Pirms radīt kaut ko jaunu, vispirms izveido sarakstu — iespējams, tev nepieciešamā atslēga jau eksistē.
curl "https://management-api.x.ai/auth/teams/$TEAM_ID/api-keys" \
-H "Authorization: Bearer $MANAGEMENT_API_KEY"
Pieprasījuma parametri
- pageSize: atslēgu skaits vienā lapā (pēc noklusējuma tiek atgrieztas visas atslēgas)
- paginationToken: žetons nākamās lapas iegūšanai, ja atslēgu skaits pārsniedz lapas izmēru
- aclFilters: atslēgu filtrēšana pēc konkrētām atļaujām
Filtrēšana pēc ACL
Tu vari iegūt tikai tās atslēgas, kurām ir noteikts piekļuves līmenis:
# Sarakstīt tikai atslēgas ar piekļuvi tērzēšanai
curl "https://management-api.x.ai/auth/teams/$TEAM_ID/api-keys?aclFilters=api-key:endpoint:chat" \
-H "Authorization: Bearer $MANAGEMENT_API_KEY"
Tieši šī filtrēšana padara revīziju pārvaldāmu arī tad, ja atslēgu ir vairāk par duci. Praksē rodas divi jautājumi, uz kuriem atbild viens pieprasījums: kurš var izsaukt dārgāko modeli un kurām atslēgām joprojām ir piešķirta zvaigznīte (wildcard). Otrais ir visnoderīgākais — aizmirsta zvaigznīte ražošanas vidē ir visbiežākā konfigurācijas kļūda, un tajā pašā laikā visklusākā.
Lapošana (Pagination)
Komandām ar daudzām atslēgām izmanto lapošanu:
# Pirmā lapa ar 10 atslēgām
curl "https://management-api.x.ai/auth/teams/$TEAM_ID/api-keys?pageSize=10" \
-H "Authorization: Bearer $MANAGEMENT_API_KEY"
# Nākamā lapa ar saņemto žetonu
curl "https://management-api.x.ai/auth/teams/$TEAM_ID/api-keys?pageSize=10&paginationToken=TOKEN_RECU" \
-H "Authorization: Bearer $MANAGEMENT_API_KEY"
Esošas atslēgas modificēšana
Modificēšana, nevis pārradīšana, nav tikai ērtības jautājums: slepenā atslēga paliek nemainīga, tāpēc nav nepieciešama izvēršana. Tas ļauj pielāgot limitus vai ierobežot atļaujas bez pakalpojuma pārtraukuma — un aizdomu gadījumā sekunžu laikā samazināt atslēgas tiesības, kamēr gatavojies tās rotācijai.
curl -X PUT "https://management-api.x.ai/auth/api-keys/$API_KEY_ID" \
-H "Authorization: Bearer $MANAGEMENT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "prod-backend-v3",
"acls": [
"api-key:endpoint:chat",
"api-key:endpoint:embed",
"api-key:model:grok-4.20-0309-reasoning"
],
"qps": 30,
"qpm": 1000,
"tpm": 3000000
}'
Ko vari modificēt
- name: pārdēvē atslēgu, lai atspoguļotu izmaiņas tās lietojumā
- acls: pievieno vai noņem atļaujas (galapunkti, modeļi)
- qps / qpm / tpm: pielāgo ātruma limitus
- expireTime: pagarini vai saīsini derīguma termiņu
Ko nevari modificēt
- Atslēgas identifikators (
api_key_id) paliek nemainīgs - Slepenā atslēga modificēšanas laikā nemainās (tam izmanto rotāciju)
- Īpašnieka komandu nevar nodot citai komandai
Pārbaudi propagāciju
Lūk, detaļa, kas izskaidro pusi no „kļūdām”, par kurām ziņo pēc atslēgas modificēšanas: izmaiņas nav momentālas visos serveros. Tikko izveidota atslēga dažus brīžus var atgriezt 401, paplašināts ACL var vēl nebūt aktīvs — un tu meklē kļūdu savā kodā, lai gan vajadzēja tikai pagaidīt. Propagācijas galapunkts pastāv tieši tāpēc, lai novērstu šīs šaubas:
curl "https://management-api.x.ai/auth/api-keys/$API_KEY_ID/propagation" \
-H "Authorization: Bearer $MANAGEMENT_API_KEY"
Šis galapunkts atgriež atslēgas propagācijas statusu. Pirms atslēgas izmantošanas ražošanas vidē, it īpaši pēc ACL modificēšanas, sagaidi, līdz propagācija ir pabeigta.
Biežākie scenāriji
Izstrādes atslēgas paaugstināšana uz ražošanas līmeni
Pāreja uz ražošanas vidi ir visbiežākais modificēšanas scenārijs, un ieradums šādā gadījumā radīt jaunu atslēgu ir dārgs: tā ir jāizvēr visur, jāatjauno drošības glabātuves (vaults), bet vecā atslēga paliek beztermiņa. Esošās atslēgas limitu paaugstināšana izvairās no visa šī.
curl -X PUT "https://management-api.x.ai/auth/api-keys/$API_KEY_ID" \
-H "Authorization: Bearer $MANAGEMENT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "prod-chatbot",
"qps": 50,
"qpm": 2000,
"tpm": 5000000
}'
Aizdomās turētas kompromitētas atslēgas ierobežošana
Aizdomu gadījumā operāciju secībai ir izšķiroša nozīme. Vispirms ierobežo — tukši ACL, nulles ātruma limiti — tas aptur noplūdi vienā pieprasījumā, neatgriezeniski neko nesabojājot. Rotācija seko vēlāk, bezsaistē, kad esi identificējis, kur atslēga tika izmantota. Pretējā gadījumā tev būs apturēta ražošanas vide un izmeklēšana, kas jāveic spriedzes apstākļos.
curl -X PUT "https://management-api.x.ai/auth/api-keys/$API_KEY_ID" \
-H "Authorization: Bearer $MANAGEMENT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"acls": [],
"qps": 0,
"qpm": 0
}'
Galvenās atziņas
GET /auth/teams/{teamId}/api-keyssaraksta visas atslēgas ar lapošanu un ACL filtrēšanuPUT /auth/api-keys/{apiKeyId}modificē parametrus, nemainot slepeno atslēguGET /auth/api-keys/{apiKeyId}/propagationpārbauda, vai izmaiņas ir stājušās spēkā- Izmanto ACL filtrēšanu, lai regulāri veiktu savas komandas piekļuves revīziju
- Pēc jebkuras modificēšanas pirms atslēgas izmantošanas ražošanas vidē pārbaudi propagāciju