Išvardinkite ir modifikuokite savo raktus
Šiame puslapyje
Tavo API raktų inventorizacija
Laikui bėgant tavo komanda sukaupia API raktų skirtingoms aplinkoms, projektams ir komandos nariams. Valdymo API leidžia išvardyti visus aktyvius raktus, filtruoti juos pagal leidimus ir keisti jų nustatymus nekurdami naujų.
Raktų išvardijimas
Šis galinis taškas yra bet kokio prieigos audito pradžia ir dažnai būtent čia atrandate tikrąją inventorizaciją: prieš aštuonis mėnesius testui sukurtą raktą, rakto, įvardinto buvusio komandos nario vardu, du gamybos raktus, kurių niekas nežino, kuris naudojamas. Prieš kurdami ką nors naujo, pirmiausia išvardinkite esamus – galbūt jums reikalingas raktas jau egzistuoja.
curl "https://management-api.x.ai/auth/teams/$TEAM_ID/api-keys" \
-H "Authorization: Bearer $MANAGEMENT_API_KEY"
Užklausos parametrai
- pageSize: raktų skaičius puslapyje (pagal nutylėjimą grąžinami visi raktai)
- paginationToken: žetonas kitam puslapiui gauti, jei raktų skaičius viršija puslapio dydį
- aclFilters: filtruoti raktus pagal specifinius leidimus
Filtravimas pagal ACL
Gali gauti tik tam tikro prieigos lygio raktus:
# Išvardyti tik raktus su pokalbių prieiga
curl "https://management-api.x.ai/auth/teams/$TEAM_ID/api-keys?aclFilters=api-key:endpoint:chat" \
-H "Authorization: Bearer $MANAGEMENT_API_KEY"
Būtent šis filtravimas leidžia valdyti auditą, kai raktų yra daugiau nei dešimt. Praktikoje kyla du klausimai, į kuriuos atsakoma viena užklausa: kas gali kviesti brangiausią modelį ir kurie raktai vis dar turi pakaitinį simbolį (wildcard). Antrasis yra naudingiausias – pamirštas pakaitinis simbolis gamyboje yra dažniausia konfigūracijos klaida ir pati tyliausia.
Puslapiavimas
Komandoms, turinčioms daug raktų, naudokite puslapiavimą:
# Pirmas 10 raktų puslapis
curl "https://management-api.x.ai/auth/teams/$TEAM_ID/api-keys?pageSize=10" \
-H "Authorization: Bearer $MANAGEMENT_API_KEY"
# Kitas puslapis su gautu žetonu
curl "https://management-api.x.ai/auth/teams/$TEAM_ID/api-keys?pageSize=10&paginationToken=TOKEN_RECU" \
-H "Authorization: Bearer $MANAGEMENT_API_KEY"
Esamo rakto modifikavimas
Modifikavimas vietoj perkūrimo yra ne tik patogumas: slaptasis raktas lieka toks pat, todėl diegti nieko nereikia. Tai leidžia koreguoti limitus arba apriboti leidimus be veiklos sutrikdymo – o įtarus saugumo pažeidimą, per kelias sekundes sumažinti rakto teises, kol ruošiatės jį pakeisti.
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
}'
Ką gali keisti
- name: pervadinti raktą, kad jis atspindėtų naudojimo pokyčius
- acls: pridėti arba pašalinti leidimus (galiniai taškai, modeliai)
- qps / qpm / tpm: koreguoti spartos limitus
- expireTime: pratęsti arba sutrumpinti galiojimo laiką
Ko keisti negali
- Rakto identifikatorius (
api_key_id) lieka nepakitęs - Slaptasis raktas modifikavimo metu nekinta (tam naudokite keitimą)
- Nuosavybės komandos perduoti negalima
Patikrink plitimą
Štai detalė, paaiškinanti pusę „klaidų“, apie kurias pranešama modifikavus raktą: pakeitimas visuose serveriuose įsigalioja ne akimirksniu. Tik ką sukurtas raktas kelias akimirkas gali grąžinti 401 klaidą, išplėstas ACL gali būti dar neaktyvus – ir tu ieškai klaidos savo kode, nors reikėjo tiesiog palaukti. Plitimo galinis taškas egzistuoja būtent tam, kad pašalintų šią abejonę:
curl "https://management-api.x.ai/auth/api-keys/$API_KEY_ID/propagation" \
-H "Authorization: Bearer $MANAGEMENT_API_KEY"
Šis galinis taškas grąžina rakto plitimo būseną. Prieš naudodamas raktą gamyboje, ypač po ACL modifikavimo, palauk, kol plitimas bus baigtas.
Dažni scenarijai
Atnaujink kūrimo raktą gamybai
Perėjimas į gamybą yra dažniausias modifikavimo scenarijus, o refleksas šia proga sukurti naują raktą yra brangus: tenka jį diegti visur, atnaujinti saugyklas, o senasis lieka be reikalo. Esamo rakto limitų didinimas viso to išvengia.
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
}'
Apribok įtariamą kompromituotą raktą
Įtarus saugumo pažeidimą, veiksmų eiliškumas yra svarbus. Pirmiausia apribok – tušti ACL, nuliniai spartos limitai – tai sustabdo nuostolius viena užklausa, nieko negrįžtamai nesugadinant. Keitimas atliekamas vėliau, neprisijungus prie tinklo, kai jau nustatei, kur raktas buvo naudojamas. Atvirkštinė tvarka paliks tave su sustabdyta gamyba ir tyrimu, kurį reikia atlikti esant spaudimui.
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
}'
Svarbiausi punktai
GET /auth/teams/{teamId}/api-keysišvardija visus raktus su puslapiavimu ir ACL filtravimuPUT /auth/api-keys/{apiKeyId}modifikuoja parametrus nekeisdamas slaptojo raktoGET /auth/api-keys/{apiKeyId}/propagationpatikrina, ar pakeitimai įsigaliojo- Naudok ACL filtravimą reguliariai audituodamas savo komandos prieigą
- Po bet kokio modifikavimo prieš naudodamas raktą gamyboje patikrink plitimą