Klucze API

Klucze API umożliwiają programowy dostęp do REST API badges.ninja. Używaj ich do automatyzacji tworzenia, wystawiania i zarządzania odznakami z poziomu własnych aplikacji.

Tworzenie klucza API

1. Otwórz stronę Klucze API z paska bocznego.
2. Kliknij Utwórz klucz API. Otworzy się formularz w wierszu:

3. Nadaj kluczowi nazwę i kliknij Utwórz. Pełny klucz zostanie wyświetlony tylko raz na zielonym banerze:

4. Skopiuj klucz od razu — pełny klucz jest wyświetlany tylko raz. Jeśli go zgubisz, będziesz musiał utworzyć nowy. Po zamknięciu banera panel pokazuje już tylko prefiks klucza (np. bws_a1b2c3d4...); pełny klucz pozostaje przechowywany po stronie serwera i służy do uwierzytelniania Twoich żądań:

Każdy wiersz pokazuje także datę utworzenia klucza oraz — po jego użyciu — znacznik czasu ostatniego użycia, dzięki czemu łatwo wychwycisz nieużywane klucze.

Zakresy dostępu

Podczas tworzenia klucza możesz ustawić go jako tylko do odczytu albo pozostawić pełny dostęp:

Zakres	Pozwala na
Pełny dostęp (domyślnie)	Odczyt i zapis — wyświetlanie danych oraz tworzenie, wystawianie, aktualizowanie lub usuwanie.
Tylko do odczytu	Wyłącznie bezpieczne żądania GET. Każde żądanie modyfikujące (POST, PUT, PATCH, DELETE) jest odrzucane z kodem 403 Forbidden.

Używaj klucza tylko do odczytu w integracjach, które muszą jedynie odczytywać dane (raporty, panele, kopie zapasowe), aby wyciek klucza nie pozwolił niczego zmienić. Zaznacz Klucz tylko do odczytu w formularzu tworzenia; takie klucze mają na liście plakietkę Tylko do odczytu. Klucze utworzone przed wprowadzeniem zakresów zachowują pełny dostęp.

Format klucza

Klucze API mają prefiks bws_, po którym następuje 32-znakowy ciąg szesnastkowy:

bws_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6

Używanie kluczy API w żądaniach

Dołącz klucz API w nagłówku X-Api-Key każdego żądania API:

curl -X GET https://api.badges.ninja/issuers \
  -H "X-Api-Key: bws_your_api_key_here"

Szczegółowe informacje o uwierzytelnianiu w API znajdziesz na stronie Uwierzytelnianie.

Limity kluczy w poszczególnych planach

Liczba kluczy API, które możesz utworzyć, zależy od Twojego planu:

Plan	Limit kluczy API
Free	1
Starter ($9/mo)	5
Pro ($29/mo)	20

Wygasanie kluczy

Każdy klucz API wygasa rok po utworzeniu. Wygasły klucz przestaje uwierzytelniać żądania, dokładnie tak, jakby został usunięty. Utwórz nowy klucz, zanim stary wygaśnie, aby uniknąć przerw w działaniu.

Usuwanie klucza

1. Otwórz stronę Klucze API.
2. Znajdź klucz, który chcesz usunąć.
3. Kliknij Usuń.
4. Potwierdź usunięcie.

Po usunięciu klucz natychmiast przestaje działać. Wszystkie aplikacje korzystające z tego klucza będą otrzymywać błędy uwierzytelniania.