Klucze API i tokeny dostępu

Klucz API to sposób, w jaki Twoje programy dostają się do API LinkHarbor. Należy do workspace, a nie do osoby, i może dokładnie to, na co pozwolisz mu przez zakresy. Do właściwych wywołań wymieniasz klucz na krótko ważny token dostępu.

#Kto może tworzyć klucze API?

• Właściciele i admini workspace – redaktorzy i czytelnicy widzą w sekcji „Callback i API” tylko kartę „Połączone aplikacje”
• Od planu Creator Pro; w Creator Free karta pokazuje „Klucze API są dostępne od planu Creator Pro.”
• Jednocześnie aktywnych: do 5 kluczy w Creator Pro, do 20 w Creator Agency, do 50 w Enterprise

Gdy limit zostanie osiągnięty, tworzenie klucza kończy się błędem 409 limit_reached. Najpierw usuń klucz, którego już nie potrzebujesz.

#Tworzenie klucza API

1. Otwórz „Callback i API” w nawigacji
2. W karcie „Klucze API” kliknij „+ Utwórz nowy klucz”
3. W polu „Nazwa (opcjonalnie)” wpisz nazwę, po której później rozpoznasz klucz, na przykład „Pipeline CI/CD” lub „Synchronizacja sklepu”
4. W sekcji „Zakresy” wybierz dla każdego obszaru „Odczyt” lub „Zapis”
5. Kliknij „Utwórz klucz”
6. Od razu skopiuj „Sekret klucza (prywatny)” i przechowuj go w bezpiecznym miejscu
7. Zamknij okno – ID klucza znajdziesz w każdej chwili na liście

„Nazwa (opcjonalnie)”

Do 64 znaków. Bez nazwy klucz pojawia się na liście jako „Klucz API #ID”.

„Zakresy”

Wymagany jest co najmniej jeden. „Zapis” automatycznie obejmuje „Odczyt” dla tego samego obszaru. Statystyki i wpłaty wspierających są tylko do odczytu, szablony workspace tylko do zapisu. Wszystkie zakresy wyjaśnia artykuł Zakresy w szczegółach.

„Sekret klucza (prywatny)”

Zaczyna się od lt_ i jest pokazywany dokładnie raz („⚠️ Widoczny tylko raz — skopiuj teraz!”). LinkHarbor przechowuje tylko jego hash i nie może go później pokazać ponownie.

„ID klucza:”

16 znaków z cyfr i wielkich liter A–F, na przykład 6F668EA6598B0692. Nie jest tajne i pojawia się na liście z przyciskiem kopiowania.

#Lista kluczy

Każdy aktywny klucz pokazuje nazwę, status „Aktywny”, ID klucza, zakresy, „Utworzono:” oraz „Ostatnio użyto:” albo „Jeszcze nie użyto”. Czas ostatniego użycia aktualizuje się przy każdym wywołaniu tym kluczem, najwyżej raz na minutę. „↺ Odśwież” przeładowuje listę.

#Wymiana klucza na token dostępu

curl -X POST https://dock.at-harbor.com/v1/token \
  -H "Content-Type: application/json" \
  -d '{"key_id":"6F668EA6598B0692","key_secret":"lt_…"}'

{ "token": "eyJhbGciOiJIUzI1NiIs…", "expires_in": 900 }

token

Token dostępu. Wysyłasz go z każdym żądaniem jako Authorization: Bearer <token>.

expires_in

Ważność w sekundach: 900, czyli 15 minut. Nie ma tokenu odświeżania – gdy token wygaśnie, po prostu pobierz nowy za pomocą ID klucza i sekretu.

Token reprezentuje workspace i ma dokładnie te zakresy, co klucz. W przeciwieństwie do osoby nie ma roli: endpointy, które panel zastrzega dla właścicieli i adminów (członkowie, płatności, zarządzanie domenami, webhooki, ustawienia workspace), są dla tokenów z kluczy API zawsze niedostępne. Wyjątkami są krótkie linki i szablony workspace, które działają z odpowiednim zakresem, oraz odczyt sekretów callbacków (bez sekretu w postaci jawnej) z read:workspaces.

#Nieudane próby i blokada

Przy api_key_locked pozostały czas znajduje się w details.retry_after_sec. Udana wymiana zeruje licznik.

#Usuwanie i wymiana klucza

1. Kliknij „Usuń” obok klucza
2. Wpisz DELETE, aby potwierdzić
3. Kliknij „Usuń na stałe”

Klucz przestaje działać natychmiast – wydane już tokeny dostępu również przestają działać od tej chwili i dostają 401 invalid_token. Nie ma przycisku rotacji. Aby zmienić klucz, utwórz nowy, przestaw na niego swój program, a potem usuń stary.

#Przy przejściu na niższy plan

Jeśli workspace przechodzi na Creator Free, wszystkie klucze API zostają unieważnione. Jeśli przechodzi na plan z mniejszą liczbą kluczy, najnowsze zostają zachowane, a pozostałe unieważnione. Unieważnione klucze nie wracają po późniejszej zmianie planu na wyższy – wtedy tworzysz nowe. Właściciele dostają e-mail z listą wyłączonych funkcji. Więcej w artykule Rezygnacja i niższy plan.

#Bezpieczeństwo

• Przechowuj sekret tylko w menedżerze sekretów lub w zmiennych środowiskowych, nigdy w kodzie źródłowym ani w repozytorium Git
• Nigdy nie używaj go w kodzie, który działa w przeglądarce lub w aplikacji na urządzeniu użytkownika
• Dla każdej aplikacji utwórz osobny klucz z jak najmniejszą liczbą zakresów
• Klucze, których już nie potrzebujesz, usuwaj od razu
• Przy podejrzeniu wycieku: usuń klucz i utwórz nowy