Klucze API

Twórz klucze API, którymi Twoje skrypty i systemy wywołują API WitCloud dla projektu - wybierz, co każdy klucz może robić i kiedy wygasa, a gdy przestanie być potrzebny, unieważnij go.

Aktualizacja

Klucz API pozwala Twoim skryptom i systemom wywoływać API WitCloud bez logowania - na przykład uruchomić harmonogram z własnego schedulera i sprawdzić, kiedy się zakończył. Klucz należy do projektu, a nie do osoby, która go utworzyła: działa tylko w tym projekcie, z zakresami, które mu nadasz, i działa dalej, gdy jego twórca opuści projekt. Unieważnij go, gdy przestanie być potrzebny.

Gdzie to znaleźć

Przejdź do Ustawienia > Klucze API. Karta jest w sekcji Produkt i pojawia się, gdy wybrany jest projekt. Strona pokazuje klucze wybranego projektu; przełącz projekt, żeby zobaczyć klucze innego.

Strona Ustawienia z kartą Klucze API w sekcji Produkt

Klucze API projektu widzą i nimi zarządzają tylko jego Właściciel, Administratorzy i Edytorzy (role).

Strona Klucze API

Na górze ramka Jak używać klucza pokazuje, jak wysłać klucz, przykładowe zapytanie i Co możesz zrobić przez API. Dokumentacja API otwiera opis wszystkich zapytań, które może wykonać klucz. Pod nią jest lista kluczy projektu, od najnowszego.

Strona Klucze API z ramką Jak używać klucza, przykładowym zapytaniem, listą tego, co można zrobić przez API, i przykładową listą kluczy z zakresami, statusem, datą wygaśnięcia i ostatnim użyciem

Lista pokazuje dla każdego klucza:

  • Nazwa - z opisem pod spodem, jeśli klucz go ma.
  • Klucz - pierwsze znaki klucza, żeby odróżnić klucze od siebie. Pełny klucz nie jest już pokazywany po utworzeniu.
  • Zakresy - co klucz może robić (zobacz Zakresy).
  • Status - Aktywny, Wygasł albo Unieważniony.
  • Wygasa - data, od której klucz przestaje działać, albo Nigdy.
  • Ostatnie użycie - kiedy klucz ostatnio wykonał zapytanie, albo Jeszcze nieużyty. Aktualizuje się najwyżej raz na minutę.
  • Utworzony przez - kto utworzył klucz.

Utwórz klucz API

  1. Kliknij Utwórz klucz API.
  2. Wpisz Nazwę (do 100 znaków), na przykład nazwę systemu, który będzie używał klucza. Opis jest opcjonalny (do 500 znaków).
  3. W sekcji Dostęp wybierz:
    • Ograniczony - klucz dostaje tylko zakresy zaznaczone poniżej. Zaznacz co najmniej jeden.
    • Pełny dostęp - klucz może wykonywać wszystkie zapytania dostępne dla kluczy API w tym projekcie, również te dodane w przyszłości.
  4. Wybierz Ważność: 7 dni, 30 dni, 90 dni (domyślnie), 365 dni, Własna data albo Nigdy. Przy opcji Własna data wybierz dzień od jutra: klucz działa do końca tego dnia w Twojej strefie czasowej.
  5. Kliknij Utwórz klucz API.

Okno Utwórz klucz API z wpisaną nazwą, dostępem Ograniczony z zaznaczonymi zakresami Uruchamianie workflow i Sprawdzanie uruchomień workflow oraz ważnością 90 dni

Daj kluczowi tylko taki dostęp, jakiego potrzebuje, i najlepiej ustaw datę wygaśnięcia: klucz z ważnością Nigdy działa, dopóki go nie unieważnisz.

Projekt może mieć do 25 aktywnych kluczy. Klucze wygasłe i unieważnione się nie liczą.

Skopiuj klucz

Okno Klucz API utworzony pokazuje nowy klucz. Kliknij ikonę kopiowania obok niego i przechowuj klucz w bezpiecznym miejscu - ze względów bezpieczeństwa jest pokazywany tylko ten jeden raz. Potem kliknij Gotowe, klucz skopiowany.

Okno Klucz API utworzony z przykładowym kluczem, przyciskiem Kopiuj i przyciskiem Gotowe, klucz skopiowany

Jeśli zgubisz klucz, nie da się go pokazać ponownie: utwórz nowy, a stary unieważnij.

Gotowe! Klucz jest na liście jako Aktywny i działa od razu.

Użyj klucza

Wysyłaj klucz w nagłówku X-Api-Key każdego zapytania albo jako Authorization: Bearer <klucz>. Klucz działa na swoim projekcie, więc nigdy nie wskazujesz projektu. Każdy klucz zaczyna się od wck_.

curl -X POST https://<WitCloud API>/api/workflow/run \
  -H "X-Api-Key: wck_…" \
  -H "Content-Type: application/json" \
  -d '{"workflowId": "<workflowId>"}'

Adres skopiuj z przykładu na stronie Klucze API, a opis wszystkich zapytań, ich pól i odpowiedzi znajdziesz tam w Dokumentacji API.

Klucz może wykonywać tylko zapytania dostępne dla kluczy API - nie zaloguje się do panelu i nie może tworzyć, wyświetlać ani unieważniać kluczy.

Zakresy

ZakresW paneluCo klucz może robićZapytań na minutę
workflows:runUruchamianie workflowUruchomić harmonogram teraz, niezależnie od jego planu. Plan się nie zmienia.10
workflows:readSprawdzanie uruchomień workflowSprawdzić status uruchomienia i kiedy się zakończyło.60
custom-queries:readPodgląd Custom QueriesPobrać konfigurację integracji Custom Queries.60
custom-queries:writeZarządzanie Custom QueriesTworzyć i edytować integracje Custom Queries.30

Pełny dostęp (*) obejmuje wszystkie zakresy powyżej.

Limity są na projekt: wszystkie klucze projektu dzielą je między siebie, więc więcej kluczy nie oznacza więcej zapytań. Każda odpowiedź podaje, ile zapytań zostało, w nagłówkach X-RateLimit-Limit, X-RateLimit-Remaining i X-RateLimit-Reset. Po przekroczeniu limitu API odpowiada 429, a nagłówek Retry-After mówi, ile sekund trzeba poczekać.

Unieważnij albo usuń klucz

  • Unieważnij (ikona przekreślonego koła, przy aktywnych kluczach) - klucz od razu przestaje działać, a wszystko, co go używa, zostaje odrzucone. Zostaje na liście jako Unieważniony.
  • Usuń (ikona kosza) - klucz zostaje unieważniony i usunięty z listy. Tej operacji nie można cofnąć.

W obu przypadkach panel prosi najpierw o potwierdzenie.

Okno Unieważnij klucz API z prośbą o potwierdzenie, że przykładowy klucz Nightly pipeline przestanie działać

Unieważnionego ani wygasłego klucza nie da się ponownie włączyć ani przedłużyć - utwórz nowy.

Rozwiązywanie problemów

Komunikaty formularza panel pokazuje po polsku, a komunikaty API po angielsku - nagłówki poniżej są w oryginalnym brzmieniu.

Nadaj kluczowi nazwę. / Wybierz co najmniej jeden zakres albo daj kluczowi pełny dostęp. / Wybierz datę wygaśnięcia.

W oknie Utwórz klucz API czegoś brakuje: wpisz Nazwę, zaznacz co najmniej jeden zakres (albo wybierz Pełny dostęp) lub wybierz dzień przy opcji Własna data.

A project can have at most 25 active API keys

Unieważnij albo usuń klucz, który nie jest już używany, a potem utwórz nowy.

Invalid API key / API key has been revoked / API key has expired

API odpowiada 401: klucz jest błędny (sprawdź, czy skopiował się w całości), został unieważniony lub usunięty albo minęła jego data w kolumnie Wygasa. Sprawdź jego Status na liście i w razie potrzeby utwórz nowy klucz.

API key does not have the "…" scope

API odpowiada 403: klucz nie ma zakresu potrzebnego do tego zapytania. Kluczy nie da się zmieniać - utwórz klucz z potrzebnym zakresem, a stary unieważnij.

This endpoint does not accept API keys

To zapytanie nie jest dostępne dla kluczy API. Zapytania, które są, znajdziesz w Dokumentacji API na stronie Klucze API.

Rate limit exceeded

API odpowiada 429: klucze projektu wykonały w ostatniej minucie za dużo zapytań tego rodzaju. Poczekaj tyle sekund, ile podaje Retry-After, i spróbuj ponownie.