Każde zapytanie do Railmail API musi być uwierzytelnione kluczem API przypisanym do projektu. Zapytania bez ważnego klucza zwracają 401.
Klucze API
Klucze mają format rm_(live|test)_<losowy>:
| Prefiks | Środowisko | Zastosowanie |
|---|
rm_live_... | Produkcyjne | Ruch produkcyjny na prawdziwych subskrybentach i kampaniach. |
rm_test_... | Testowe | Rozwój i testy bez wpływu na dane produkcyjne. |
Traktuj klucze API jak hasła. Nigdy nie umieszczaj ich w repozytorium ani w kodzie po stronie klienta. Przechowuj je w zmiennych środowiskowych lub menedżerze sekretów.
Wysyłanie klucza
Przekaż klucz w nagłówku X-API-Key:
curl https://api.railmail.app/api/v1/subscribers \
-H "X-API-Key: rm_live_twoj_klucz"
Authorization:
curl https://api.railmail.app/api/v1/subscribers \
-H "Authorization: Bearer rm_live_twoj_klucz"
Zakresy
Każdy klucz posiada zestaw zakresów (scopes). Każda operacja wymaga określonego zakresu, opisanego w jej opisie (na przykład Requires scope: subscribers:write). Zapytanie, którego klucz nie ma wymaganego zakresu, zwraca 403 — to różnica względem 401, który oznacza brak lub nieważny klucz.
Pełna taksonomia zakresów:
| Zasób | Zakresy |
|---|
| Subskrybenci | subscribers:read, subscribers:write |
| Tematy | topics:read, topics:write |
| Segmenty | segments:read, segments:write |
| Kampanie | campaigns:read, campaigns:write |
| Automatyzacje | automations:read, automations:write |
| Pola niestandardowe | custom_fields:read, custom_fields:write |
| Domeny wysyłkowe | sending_domains:read, sending_domains:write |
| Zgody | consents:manage |
| Wykluczenia | suppressions:manage |
| Raporty | reports:read |
| Rozliczenia | billing:read |
| Kredyty AI | credits:read |
Przyznawaj każdemu kluczowi tylko te zakresy, których potrzebuje. Klucz służący wyłącznie do synchronizacji subskrybentów nie potrzebuje campaigns:write ani billing:read.
