Klucze API
Na tej stronie
Klucze API pozwalają Twojemu własnemu oprogramowaniu — lub dowolnemu systemowi firmy zewnętrznej obsługującemu BYOK (Bring Your Own Key) — korzystać z modeli publikowanych przez Performance Hub. Kluczami zarządza się w Settings (koło zębate) → Service Access & API Keys. Aby nimi zarządzać, musisz mieć rolę Organisation Administrator.
*"Wygeneruj klucze API, aby oprogramowanie i systemy innych firm obsługujące podejście BYOK (Bring Your Own Key) mogły łączyć się z modelami publikowanymi przez Performance Hub."*j
Rysunek 1: Lista kluczy API: etykieta, zamaskowany klucz, stan, wydatki i limity, modele, ostatnie użycie i akcje wiersza
Lista kluczy
| Kolumna | Znaczenie |
|---|---|
| Label | Opcjonalna nazwa nadana kluczowi. |
| Key | Zamaskowany klucz (np. phk_7Qm2…Xa9LkP) — pełny sekret nie jest już nigdy wyświetlany po utworzeniu. |
| Status | Active, Provisioning… (przez chwilę, podczas konfigurowania nowego klucza) lub Disabled (unieważniony; wiersz jest przyciemniony). |
| Spend / limits | Wydatki od początku istnienia klucza i postęp względem limitów wydatków ustawionych dla klucza. |
| Models | all lub liczba modeli, do których klucz jest ograniczony. |
| Last used | Kiedy klucz ostatnio wykonał żądanie. |
| Actions | Edit, Rotate, Revoke (lub Re-activate), Delete. |
Jeśli korzystasz z Workflows, wiersz Workflows pokazuje Managed service zamiast zamaskowanego klucza. Gdy nie ma żadnych kluczy, lista wyświetla komunikat "No API keys yet."
Tworzenie klucza
Kliknij Create key. Otworzy się panel Create API key:
Rysunek 2: Panel Create API key: etykieta, typ połączenia, limity wydatków, limity liczby żądań, ograniczenie modeli i zastąpienie zabezpieczeń
| Ustawienie | Działanie |
|---|---|
| Label (optional) | Nazwa klucza, zwykle odpowiadająca systemowi, dla którego jest przeznaczony (na przykład Hotel Concierge App, Clinic Intake Assistant lub Booking Website). Zdecydowanie zalecane — to według etykiet przypisywane jest wykorzystanie na kartach Activity i Logs. |
| Connection type | API key — "Generic API keys remain in the API Keys list." External agent — "External agents appear under Connected Services and use this key to authenticate." Ustawiany podczas tworzenia klucza; nie można go później zmienić. |
| Set spend limits for this key | "Set any combination of daily, monthly and lifetime caps for this key." — Daily limit ("Resets at the start of each day (facility timezone)."), Monthly limit ("Resets on the 1st of each month (facility timezone).") i Lifetime cap ("Total spend over the lifetime of this key. Never resets."). |
| Rate limits (optional) | "Cap requests and tokens per minute for this key. Leave blank for unlimited." — Requests / min i Tokens / min. |
| Restrict models for this key | "Only the selected models will be usable with this key." Wybierz spośród modeli włączonych dla obiektu. |
| Override facility guardrails for this key | "Select none to explicitly disable guardrails for this key." Po włączeniu ten klucz korzysta z własnego wyboru zabezpieczeń zamiast wyboru obiektu — łącznie z opcją „none”. Zobacz Guardrails. |
Kliknij Create key.
Jednorazowo wyświetlany sekret
Nowy klucz jest wyświetlany jeden raz, w oknie dialogowym Copy your API key:
Rysunek 3: Nowy klucz jest wyświetlany jeden raz: skopiuj go przed zamknięciem okna dialogowego
*"Jest to jedyny moment, w którym pełny klucz jest wyświetlany. Przechowuj go w bezpiecznym miejscu."*j
Przed kliknięciem Done skopiuj klucz do swojego menedżera sekretów. Po zamknięciu tego okna wyświetlana jest już tylko zamaskowana postać klucza. Jeśli utracisz sekret, użyj akcji Rotate, aby uzyskać nowy.
Edytowanie klucza
Kliknij wiersz klucza (lub jego ikonę ołówka Edit), aby otworzyć panel Configure API key — z tymi samymi ustawieniami co przy tworzeniu (etykieta, limity wydatków, limity liczby żądań, ograniczenie modeli, zastąpienie zabezpieczeń):
Rysunek 4: Panel Configure API key
Zmiany zaczynają obowiązywać chwilę po zapisaniu. Gdy klucz ma limity dzienne/miesięczne, jego wiersz pokazuje wykorzystanie względem nich (Today, This month, Lifetime) oraz plakietkę Limit reached po osiągnięciu limitu.
Cykl życia klucza: rotacja, unieważnienie, usunięcie
Każda akcja ma okno dialogowe z potwierdzeniem, które dokładnie opisuje, co się stanie:
| Akcja | Skutek | Tekst potwierdzenia |
|---|---|---|
| Rotate | Wystawia nowy sekret (wyświetlany jeden raz) z tymi samymi ustawieniami; stary sekret natychmiast przestaje działać. | "A new key will be issued and the current key will stop working immediately." "You will need to reconfigure any services still using the old key. This cannot be undone." |
| Revoke | Natychmiast wyłącza klucz, w sposób odwracalny. | "This key will be disabled immediately and any services using it will stop working. You can re-activate it again later." |
| Re-activate | Przywraca unieważniony klucz (ten sam sekret). | Brak — wykonywana natychmiast. |
| Delete | Trwale usuwa klucz. | "This permanently deletes the key and any services using it will stop working. This cannot be undone." |
Rysunek 5: Potwierdzenie Delete API key
Co wybrać: rotuj klucz w razie podejrzenia wycieku (usługa zachowuje ustawienia i historię — wystarczy zaktualizować sekret); unieważnij go, aby tymczasowo wstrzymać system; usuwaj go tylko wtedy, gdy integracja zniknęła na dobre.
Łączenie za pomocą klucza
Karta Connecting to the API pod listą kluczy pokazuje bazowy adres URL i przykładowe żądanie do skopiowania dla Twojego środowiska. Pełny szybki start z przykładami SDK i obsługą błędów znajdziesz w artykule Łączenie aplikacji.