Klucze API i zakresy

Każde żądanie do Sursa API jest wysyłane z kluczem API Twojej organizacji. Klucz należy do organizacji, a nie do osoby: działa dalej, gdy pracownik, który go utworzył, odchodzi z firmy, a to, co klucz może robić, ustawia się w samym kluczu.

Co klucz może robić

Trzy ustawienia klucza decydują o tym, co żądanie z tym kluczem może widzieć i zmieniać. Każde z nich jedynie zawęża pozostałe.

Ustawienie	Za co odpowiada
Rola	`admin`, `editor`, `verifier` lub `viewer` – te same role, które mają ludzie. Klucz może robić to, co użytkownik z tą rolą.
Zakresy	Które części API klucz może wywoływać, np. `cards:read` lub `webhooks:manage`. Zob. Zakresy klucza.
Profil dostępu	Opcjonalny. Ogranicza klucz do kategorii wiedzy, na które pozwala profil, tak jak użytkownika z tym profilem.

Klucz można też ograniczyć do wybranych kolekcji i nadać mu datę wygaśnięcia. Żądanie wykraczające poza te ograniczenia kończy się błędem: brak zakresu zwraca 403 z kodem api_keys.scope, a obiekt, którego klucz nie może widzieć, zwraca 404, dokładnie tak, jakby nie istniał.

Daj każdej integracji własny klucz z najwęższą rolą i zakresami, jakich potrzebuje. Zadanie synchronizacji, które tylko zapisuje dokumenty, nie potrzebuje admin; zadanie raportujące nie potrzebuje zakresów zapisu.

Utwórz klucz

Administrator organizacji tworzy klucze w Sursie w sekcji Administration → API keys (administracja → klucze API) albo za pomocą POST /v1/api-keys, używając klucza lub sesji z rolą admin:

curl -X POST https://api.sursa.com/v1/api-keys \
  -H "Authorization: Bearer $SURSA_ADMIN_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CRM sync",
    "role": "editor",
    "expires_at": "2027-06-30T00:00:00Z"
  }'

Odpowiedź zawiera wartość klucza w key. Jest ona pokazywana tylko raz: Sursa przechowuje jedynie jej skrót (hash) i nie może pokazać jej ponownie. Klucz ma postać kb_, po którym następują 43 znaki; pierwsze znaki (prefix) są widoczne na liście kluczy, aby można było odróżnić klucze od siebie.

Bez scopes klucz otrzymuje zakresy swojej roli. Przekaż scopes, aby go dodatkowo zawęzić. Bez expires_at klucz nie wygasa.

Przechowuj klucze w tajemnicy

Przechowuj klucze w menedżerze sekretów lub w zmiennych środowiskowych swojej usługi, nigdy w kodzie źródłowym.
Używaj kluczy tylko na swoich serwerach. Sursa przyjmuje żądania z przeglądarek (CORS jest otwarty), ale klucz na stronie internetowej jest widoczny dla każdego, kto ją otworzy.
Nigdy nie wysyłaj klucza w adresie URL. Wysyłaj go tylko w nagłówku Authorization.
Jeśli klucz wycieknie, natychmiast go unieważnij i utwórz nowy.

Sprawdź klucz

GET /v1/me zwraca klucz, jego rolę, efektywne zakresy, profil dostępu, datę wygaśnięcia i limit częstotliwości. Działa z każdym prawidłowym kluczem, niezależnie od jego zakresów, więc używaj tej operacji jako testu połączenia swojej integracji i przy badaniu błędu 403.

Wymień klucz

Wymiana (rotacja) zastępuje klucz bez zatrzymywania integracji. Najszybciej jest wymienić wartość klucza: POST /v1/api-keys/{key_id}/roll wydaje nową wartość tego samego klucza, z tą samą rolą, zakresami, kolekcjami i datą wygaśnięcia. Poprzednia wartość działa dalej przez overlap_hours (domyślnie 24 godziny, maksymalnie 168), więc w tym czasie możesz wdrożyć nową wartość; POST /v1/api-keys/{key_id}/revoke-previous wcześniej kończy okres nakładania.

Aby zamiast tego zastąpić klucz innym kluczem:

Utwórz nowy klucz z tą samą rolą, zakresami i profilem dostępu.
Wdróż nowy klucz w swojej integracji.
Obserwuj stary klucz w Administration → API keys (lub last_used w GET /v1/api-keys), aż przestanie być używany.
Unieważnij stary klucz.

Ustawiaj kluczom datę wygaśnięcia i wymieniaj je przed jej upływem. Sursa ostrzega administratorów organizacji, zanim klucz wygaśnie; wygasły klucz zwraca 401 z kodem api_keys.expired.

Unieważnij klucz

Unieważnij klucz w Administration → API keys lub za pomocą DELETE /v1/api-keys/{key_id}. Unieważnienie zaczyna obowiązywać w ciągu kilku sekund na każdym serwerze API. Żądania z unieważnionym kluczem zwracają 401 z kodem auth.not_authenticated.

Klucze własnego źródła

Własne źródło ma własny rodzaj klucza. Taki klucz zaczyna się od kbsrc_, może tylko zapisywać dokumenty w tym jednym źródle i nie może niczego odczytywać ani wyszukiwać. To najbezpieczniejszy klucz, jaki można przekazać platformie integracyjnej, np. Zapier. Utwórz go na stronie źródła w sekcji API keys (klucze API źródła) lub za pomocą POST /v1/sources/{source_id}/push-keys.

Gdy klucze nie są dostępne

Klucze API są częścią planu organizacji. Jeśli plan ich nie obejmuje, utworzenie klucza i każde żądanie z kluczem zwracają 403 z kodem api_keys.feature_disabled.