Dokumentacja API
Wprowadzenie
Uwierzytelnianie
API używa kluczy API przypisanych do tenanta (nie do użytkownika). Każde żądanie musi zawierać ważny klucz, a zakres operacji ogranicza zestaw uprawnień (scopes) nadanych temu kluczowi.
Klucz API
Klucze tworzysz i odwołujesz w panelu, w sekcji /app/settings/api-keys. Klucz ma prefiks onb_ i pełną wartość widać tylko raz w momencie utworzenia — w bazie przechowujemy wyłącznie skrót SHA-256, więc klucza nie da się odczytać później.
Traktuj klucz jak hasło
Klucz daje dostęp do danych osobowych pracowników. Przechowuj go po stronie serwera (zmienne środowiskowe / sekrety), nigdy w kodzie front-endu ani w repozytorium. Podejrzany klucz natychmiast odwołaj w panelu i wygeneruj nowy.Przekazanie klucza
Klucz przekazujesz w nagłówku. Obie metody są równoważne — wybierz jedną:
Authorization: Bearer onb_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
X-Onboardly-Api-Key: onb_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxcurl -H "Authorization: Bearer onb_..." \
"https://www.onboardly.work/api/v1/employees?pageSize=50"Zakresy (scopes)
Każdy klucz ma przypisany zestaw zakresów. Wywołanie endpointu bez wymaganego zakresu kończy się błędem 403 forbidden_scope. Nadawaj klucze zgodnie z zasadą minimalnych uprawnień.
| Zakres | Uprawnia do |
|---|---|
read:employees | odczyt i eksport kartotek pracowników |
write:employees | import, aktualizacja (PATCH), wyrejestrowanie ZUS |
read:payroll | odczyt list płac i rozliczeń |
read:invoices | odczyt rachunków / faktur |
Tenant-scope
Klucz jest jednoznacznie powiązany z tenantem. Wszystkie zasoby zwracane przez API są automatycznie ograniczone do danych tego tenanta — nie ma możliwości odczytania cudzych danych, nawet znając identyfikator zasobu (taki przypadek zwróci 404 not_found).
Audyt dostępu do PII
Każdy odczyt lub eksport kartoteki pracownika (z odszyfrowanymi danymi osobowymi) zapisuje wpis audytu zgodnie z art. 30 RODO. Dzięki temu zawsze wiadomo, który klucz i kiedy sięgnął po dane wrażliwe.