Szybki start

Postępuj zgodnie z Przewodnikiem po uwierzytelnianiu, aby się zalogować, a następnie otwórz stronę Kluczy zarządzających i utwórz klucz zarządzający. Przechowuj go oddzielnie od standardowych kluczy aplikacji. Wysyłaj go jako token Bearer wyłącznie do endpointów zarządzania platformą.

Standardowy klucz API nie może wywoływać punktów końcowych zarządzania kluczami ani barierami ochronnymi. Prawidłowy klucz zarządzający może nadal otrzymywać odpowiedź 403 Forbidden, gdy jego właściciel nie posiada już wymaganej roli na koncie.

Użyj GET /api/v1/keys, aby sprawdzić klucze widoczne dla konta klucza zarządzającego:

Używaj zwróconych publicznych identyfikatorów do późniejszych żądań pobrania, aktualizacji, odwołania lub przypisania guardrail. Nigdy nie wywnioskuj dostępu na podstawie nazwy klucza ani zamaskowanego tokenu.

Utwórz klucz aplikacji za pomocą POST /api/v1/keys. Pełny tajny klucz jest zwracany tylko w odpowiedzi na tworzenie, więc zapisz go w swoim menedżerze tajnych kluczy przed odrzuceniem tej odpowiedzi. Rotacja powinna polegać na utworzeniu zamiennika, wdrożeniu go w aplikacji, weryfikacji ruchu, a następnie unieważnieniu starego klucza.

credit_limit_windows akceptuje dowolną kombinację 1h, 1d i 7d kroczących limitów wydatków. Jeśli jakiekolwiek skonfigurowane okno zostanie wyczerpane, wywołania z tym kluczem zwracają 429 Too Many Requests do czasu, gdy użycie opuści okno. Wyślij pusty obiekt podczas aktualizowania klucza, aby wyczyścić wszystkie kroczące limity.

Gdy żądanie utworzenia pomija wszystkie pola limitów wydatków oraz guardrail_id, nowy klucz używa domyślnych ustawień zarządzania obszaru roboczego. Jawne limity, ruchome okna lub guardrail zastępują ten domyślny wybór. Wyślij credit_limit_cents: null, aby utworzyć nieograniczony limit natywny. Podana kwota bez okresu resetowania pozostaje limitem na cały okres użytkowania. Aktualizacje nigdy nie stosują ponownie ustawień domyślnych obszaru roboczego, a ich zmiana nie zmienia istniejących kluczy.

Tworzenie i aktualizacja przyjmują tags, tablicę pełnych ciągów key:value. Odpowiedzi listy, pobierania, tworzenia i aktualizacji zwracają całą tablicę. PATCH zastępuje tablicę; pominięcie tags ją zachowuje. Klucz musi mieć 1–32 znaki, a wartość 1–64, dokładnie jeden dwukropek i bez białych znaków. Dozwolonych jest najwyżej 20 różnych tagów, wliczając predefiniowane. Nieprawidłowy format lub sprzeczne ustawienia zwracają 422 z błędami walidacji tagów; wartość niebędąca tablicą lub element niebędący ciągiem zwraca 400.

Wymagany jest dokładnie jeden tag przeznaczenia: usage:developer lub usage:service. Tworzenie przez Management API dodaje usage:service, gdy nie podano przeznaczenia, również dla tags: []. Tworzenie w Dashboard i aktualizacja tagów bez przeznaczenia używają usage:developer. Istniejące klucze są migrowane jako Developer. Środowisko jest opcjonalne i dopuszcza najwyżej jedno z env:production, env:staging lub env:dev (env:prod nie jest akceptowane).

Tworzenie/edycja w Dashboard udostępnia szybki wybór przeznaczenia i środowiska, własne tagi oraz sugestie wyłącznie z nieusuniętych kluczy standardowych bieżącego obszaru roboczego. Listy pokazują wartości, a po najechaniu pełny tag. Tagi nie zmieniają właściciela klucza, widoczności ani uprawnień. Mogą powiązać klucz ze wspólnym budżetem tagu.

Administratorzy obszaru roboczego ustawiają wymagane tagi członka w sekcji Zespół, przez formularz budżetu członka. Wymagane tagi to własne tagi rozróżniające wielkość liter, np. team:growth. Przestrzenie nazw usage: i env: są zastrzeżone. Członek może mieć najwyżej 19 wymaganych tagów, a każdy klucz nadal ma limit łącznie 20 tagów.

Każdy nowy klucz standardowy automatycznie zawiera wymagane tagi właściciela w danym obszarze roboczym. Podczas tworzenia przesłane tagi są łączone z wymaganymi przed walidacją. Na przykład, jeśli członek wymaga team:growth, żądanie utworzenia przez Management API z tags: ["project:chatbot"] zwróci project:chatbot, team:growth i domyślny usage:service.

Żądanie PATCH zawierające tags musi zachować każdy wymagany tag. Usunięcie wymaganego tagu zwraca 422 z błędem walidacji wskazującym brakujące tagi, nawet gdy wywołującym jest administrator. Pominięcie tags zachowuje tagi klucza. Członkowie nadal mogą dodawać i usuwać zwykłe tagi.

Aby usunąć wymagany tag, administrator zmienia konfigurację członka w sekcji Zespół. Zapis dodaje nowe wymagane tagi do wszystkich istniejących kluczy standardowych tego członka i usuwa wycofane wymagane tagi. Pozostałe tagi nie zmieniają się. Dotyczy to także kluczy wyłączonych i wygasłych, ale nie usuniętych. Jeśli którykolwiek klucz nie może przyjąć końcowego zestawu tagów, cały zapis kończy się niepowodzeniem, a formularz wskazuje klucz do poprawienia.

Budżety tagów używają bieżących tagów każdego klucza. Zmiana wymaganych tagów zmienia też przypisanie istniejących wydatków do budżetów w bieżącym okresie. Dodanie wymaganego tagu może natychmiast wyczerpać jego budżet. Istniejący członkowie początkowo nie mają wymaganych tagów, a ich klucze pozostają niezmienione, dopóki administrator nie zapisze konfiguracji.

Guardrails to wielokrotnego użytku zasady konta dotyczące kontroli modelu, dostawcy i wydatków. Zarządzaj zasadami za pomocą /api/v1/guardrails, a następnie używaj /api/v1/guardrail_assignments do ich dołączania lub usuwania. Traktuj odrzucone przypisanie jako błąd zasad lub własności zamiast po cichu kontynuować bez guardrail.

Utwórz dodatnią regułę w trybie block, a następnie przypisz jej guardrail_id i tag uwzględniający wielkość liter, np. dept:ml. Wybierz dokładnie jeden cel, api_token_id, account_user_id lub tag. Budżety tagów wymagają administratora. Wyłączone budżety nie egzekwują limitów. Żądania zarządzania nie zużywają budżetu.

Budżety agregują bieżące tagi kluczy standardowych, w tym wydatki usuniętych, wyłączonych i wygasłych kluczy. Dodanie lub usunięcie tagu przenosi wydatki klucza z bieżącego okresu. Utworzenie lub odtworzenie budżetu nigdy nie zeruje wydatków. Liczba kluczy pomija usunięte klucze. Każdy pasujący budżet musi dopuścić żądanie; odmowa zwraca 403 i nazwę tagu.

Wartość null pola credit_limit_reset_interval oznacza limit bezterminowy. Pozostałe okresy używają UTC. Próg alertu domyślnie wynosi 80 i przyjmuje wartości od 1 do 100. Bezpośrednie zmiany dotyczą wszystkich przypisań; panel najpierw kopiuje politykę przy edycji budżetu tagu.

Przyjmowanie żądań sprawdza rezerwacje. Rozliczenie może je przekroczyć, pokazać użycie ponad 100% i zablokować kolejne płatne żądania. Logi używają czasu utworzenia logu; oczekujące zadania i partie własnego czasu utworzenia. Zadanie przyjęte wcześniej może zostać rozliczone w późniejszym okresie.