Pereiti prie pagrindinio turinio
Lietuvių— Pasirinkite kalbą
Meniu

Išvardinkite ir modifikuokite savo raktus

Paskaita 3 iš 14 Atnaujinta 2026 m. liepos 29 d. Kūrėjas
Šiame puslapyje
  1. Tavo API raktų inventorizacija
  2. Raktų išvardijimas
  3. Esamo rakto modifikavimas
  4. Patikrink plitimą
  5. Dažni scenarijai
  6. Svarbiausi punktai

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-keys išvardija visus raktus su puslapiavimu ir ACL filtravimu
  • PUT /auth/api-keys/{apiKeyId} modifikuoja parametrus nekeisdamas slaptojo rakto
  • GET /auth/api-keys/{apiKeyId}/propagation patikrina, ar pakeitimai įsigaliojo
  • Naudok ACL filtravimą reguliariai audituodamas savo komandos prieigą
  • Po bet kokio modifikavimo prieš naudodamas raktą gamyboje patikrink plitimą