Uwierzytelnianie i scopes

Każde żądanie do API uwierzytelnia klucz API organizacji. Nie ma logowania użytkownika ani tokenów OAuth.

Klucz API

Klucz to jeden tajny string:

rez_live_8fK2mQ9x_Zt4vN7pL1sQ8wE3rY6uI0oP2aS5dF9gHjK3lM7nB
└──┬───┘ └──┬───┘ └───────────────────┬────────────────────┘
środowisko  key_id                   sekret

Środowisko — live, czyli produkcja.
key_id — 8 znaków, jawny identyfikator. Panel pokazuje go jako prefiks rez_live_8fK2mQ9x.
Sekret — losowy ciąg znaków. Rezeri przechowuje tylko jego skrót, więc nikt nie odczyta go ponownie.

Pełny klucz zobaczysz tylko raz, zaraz po utworzeniu. Zgubiony klucz odwołaj i utwórz nowy.

Klucz jest serwerowy. Trzymaj go w zmiennej środowiskowej albo menedżerze sekretów, nigdy w repozytorium, kodzie przeglądarki ani aplikacji mobilnej.

Nagłówek `Authorization`

curl https://api.rezeri.com/v1/services \
  -H "Authorization: Bearer rez_live_8fK2mQ9x_..."

Brak nagłówka albo inny schemat niż Bearer daje 401 missing_api_key.

Zarządzanie kluczami

Klucze tworzy i odwołuje wyłącznie właściciel organizacji, w panelu: Ustawienia → API i webhooki. Inni członkowie zespołu nie widzą tej sekcji.

Przy tworzeniu klucza podajesz:

nazwę — np. „Strona www” albo „Integracja CRM”;
scopes — co klucz może robić (niżej);
domeny powrotu — dokąd klient może wrócić po płatności online (niżej).

Organizacja może mieć wiele kluczy. Klucz do rotacji utwórz przed odwołaniem starego — wymiana obędzie się bez przestoju. Odwołany klucz od razu przestaje działać (401 invalid_api_key).

Panel pokazuje przy kluczu datę ostatniego użycia (z dokładnością do minuty).

Scopes

Scope	Pozwala na
`services:read`	odczyt usług
`staff:read`	odczyt pracowników
`availability:read`	odczyt wolnych terminów
`bookings:read`	odczyt i listę rezerwacji
`bookings:write`	tworzenie rezerwacji, sesję płatności, anulowanie
`webhooks:manage`	zarządzanie webhookami

Wymagany scope każdej operacji podaje referencja API (pole x-required-scopes i opis operacji). Nadawaj kluczowi tylko te scopes, których integracja potrzebuje. Klucz bez wymaganego scope’u dostaje 403 insufficient_scope, a detail podaje brakujący scope.

Domeny powrotu

Lista domen powrotu chroni przed przekierowaniem klienta na obcą stronę. Adres return_url w tworzeniu rezerwacji i w sesji płatności musi:

mieć schemat https;
mieć host z listy domen klucza.

Wpis example.com pasuje tylko do hosta example.com. Subdomeny dopuszcza wpis *.example.com — pasuje do shop.example.com, ale nie do samego example.com. Wielkość liter nie ma znaczenia.

Adres spoza listy daje 422 return_url_not_allowed. Klucz bez domen powrotu nie otworzy płatności online. Zobacz Płatności online.

Kolejność sprawdzeń

Każde żądanie przechodzi te kontrole po kolei. Pierwsza nieudana kończy żądanie:

#	Kontrola	Błąd
1	Nagłówek `Authorization: Bearer` jest obecny	`401 missing_api_key`
2	Klucz ma poprawny format	`401 invalid_api_key`
3	Prefiks klucza pasuje do środowiska (`rez_live_`)	`401 wrong_environment`
4	Klucz istnieje, sekret się zgadza, klucz nie jest odwołany	`401 invalid_api_key`
5	Organizacja jest dostępna (konto właściciela aktywne i nie w trakcie usuwania)	`403 organization_unavailable`
6	Plan organizacji obejmuje dostęp do API	`403 plan_required`
7	Klucz `live`: organizacja ma włączony dostęp do API	`403 api_not_enabled`
8	Klucz ma scope wymagany przez endpoint	`403 insufficient_scope`

invalid_api_key nie mówi, czy klucz nie istnieje, ma zły sekret, czy został odwołany. Tak ma być.

Od kontroli 5 żądanie liczy się do limitu klucza, także gdy kończy się błędem. Kontrole 5–7 biegną przy każdym żądaniu. Po zmianie planu na niższy klucze dostają 403 plan_required, ale nie znikają — znów działają po powrocie na plan z dostępem do API (zobacz cennik). Odwołać je w panelu możesz także na niższym planie.

Żądania z brakującym albo odrzuconym kluczem (401) liczą się do osobnego limitu nieudanych prób na adres IP. Zobacz Limity.

Środowisko

API ma jedno środowisko — produkcję pod https://api.rezeri.com/v1. Przyjmuje tylko klucze rez_live_. Klucz z innym prefiksem środowiska (np. rez_test_) daje 401 wrong_environment. Jak sprawdzić integrację na własnym koncie: Testowanie integracji.