Tworzenie i konfigurowanie klucza API
Na tej stronie
Dlaczego tworzyć klucze przez API
Ręczne tworzenie klucza zajmuje trzydzieści sekund – właśnie dlatego potrzebujesz automatyzacji. Ponieważ jest to szybkie, robisz to bez zastanowienia: brak konwencji nazewnictwa, brak limitów przepustowości, tylko wildcard „żeby działało szybko“. Sześć miesięcy później nikt nie wie, do czego służy dany klucz.
Użycie API wymusza nadawanie nazw, określanie zakresu i limitów dla każdego klucza, ponieważ są to parametry skryptu. Spójność przestaje być dyscypliną, którą musisz utrzymywać, a staje się właściwością kodu. Możesz zautomatyzować tworzenie kluczy dla swoich środowisk (dev, staging, production), stosować szczegółowe listy kontroli dostępu (ACL) i definiować limity przepustowości – wszystko w ramach skryptów wdrażania lub narzędzi infrastrukturalnych.
Punkt końcowy tworzenia
Aby utworzyć klucz API, wyślij żądanie POST do następującego punktu końcowego:
POST /auth/teams/{teamId}/api-keys
Treść żądania
{
"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"
}
Szczegółowe parametry
name (wymagane): czytelny identyfikator Twojego klucza. Wybierz nazwę opisową, która wskazuje na przeznaczenie (prod-backend, staging-chatbot, dev-john). Nazwa ta pojawia się w konsoli i w logach użycia.
acls (wymagane): lista uprawnień przyznanych temu kluczowi. Dostępne są dwa formaty:
api-key:endpoint:[endpoint]— ogranicza dostępne punkty końcowe (chat, embed, image, models, sample, tokenize, documents)api-key:model:[model]— ogranicza dostępne modele (grok-4.20-0309-reasoning, grok-4.3 itp.)
Znak * działa jako wildcard: api-key:endpoint:* autoryzuje wszystkie punkty końcowe, api-key:model:* wszystkie modele. Rezerwuj to do lokalnego rozwoju. W środowisku produkcyjnym wildcard oznacza, że skompromitowany klucz daje dostęp do wszystkiego, co może zrobić Twój zespół – w tym do najdroższych modeli, z których Twoja aplikacja może nigdy nie korzystać.
qps (opcjonalne): zapytania na sekundę — maksymalna liczba żądań na sekundę.
qpm (opcjonalne): zapytania na minutę — maksymalna liczba żądań na minutę.
tpm (opcjonalne): tokeny na minutę — maksymalna liczba tokenów przetwarzanych na minutę.
expireTime (opcjonalne): data wygaśnięcia w formacie ISO 8601. Klucz zostanie automatycznie wyłączony w tym terminie.
Pełny przykład z użyciem 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"
}'
Odpowiedź zawiera klucz tajny, który nigdy więcej nie zostanie wyświetlony. Zasada ta ma praktyczną konsekwencję, którą musisz przewidzieć przed uruchomieniem skryptu, a nie po: jeśli tworzysz klucze w pętli, ich zapis musi nastąpić w tym samym ruchu. Klucz utracony między utworzeniem a rejestracją nie podlega odzyskaniu – musisz go usunąć i zacząć od nowa. Zapisz go w sejfie (Vault, AWS Secrets Manager), a nie na standardowym wyjściu terminala, gdzie trafi do Twojej historii.
Zalecane strategie ACL
Klucz deweloperski (szeroki)
{
"acls": ["api-key:endpoint:*", "api-key:model:*"],
"qps": 5,
"qpm": 50
}
Idealny do lokalnego rozwoju: dostęp jest szeroki, ponieważ z góry nie wiesz, co będziesz testować, ale limity przepustowości pozostają niskie. To właściwy kompromis – nieskończona pętla napisana przez pomyłkę w piątkowy wieczór będzie kosztować kilka centów, a nie kilkaset euro.
Klucz produkcyjny (ograniczony)
{
"acls": [
"api-key:endpoint:chat",
"api-key:model:grok-4.20-0309-reasoning"
],
"qps": 50,
"qpm": 2000,
"tpm": 5000000
}
W środowisku produkcyjnym zasada jest odwrotna: wyjdź od tego, co aplikacja faktycznie robi, i autoryzuj tylko to. Pytanie, które należy sobie zadać przy pisaniu ACL, jest zawsze takie samo – jeśli ten klucz wycieknie jutro, co osoba trzecia będzie mogła z nim zrobić? Klucz ograniczony do czatu na jednym modelu i capped do dziesięciu żądań na sekundę daje krótką odpowiedź.
Klucz tymczasowy (wygasający)
{
"acls": ["api-key:endpoint:*", "api-key:model:*"],
"expireTime": "2026-04-10T00:00:00Z"
}
Automatyczne wygasanie rozwiązuje problem, którym nikt się nie zajmuje: klucze, o których ludzie zapominają usunąć. POC, demonstracja, tymczasowy wykonawca – we wszystkich tych przypadkach expireTime gwarantuje, że dostęp sam się wyłączy. To jedyny niezawodny sposób na utrzymanie czystej inwentaryzacji, ponieważ nie polega on na niczyjej pamięci.
Dostępne punkty końcowe ACL
Aby zobaczyć punkty końcowe, których możesz użyć w ACL, sprawdź:
GET /auth/teams/{teamId}/endpoints
Dostępne punkty końcowe to: chat, embed, image, models, sample, tokenize, documents. Lista ta może ewoluować w czasie, więc sprawdzaj ją regularnie.
Kluczowe wnioski
- Tworzenie klucza odbywa się poprzez
POST /auth/teams/{teamId}/api-keys - ACL przyjmują format
api-key:endpoint:[nazwa]lubapi-key:model:[nazwa] - Wildcard
*przyznaje pełny dostęp do wszystkich punktów końcowych lub modeli - Klucz tajny jest wyświetlany tylko raz podczas tworzenia – zapisz go natychmiast
- Zawsze definiuj limity przepustowości (
qps,qpm,tpm) dostosowane do użycia - Używaj
expireTimedla kluczy tymczasowych