Uwierzytelnianie REST API dla Polska
Klucze bearer, OAuth2 PKCE i mTLS — uwierzytelnianie REST API dla klientów w Polska.
Architektura — Klucze API (server-to-server)
Generuj klucze API w dashboardzie z zakresem kraju (Polska) i roli (read-only, zamówienia, faktury, admin). Wysyłaj jako Authorization: Bearer cm_live_… przez TLS 1.3. Prefiksy środowiskowe (cm_live_, cm_test_), rotacja zero-downtime z 24-godzinnym oknem nakładania. Nie umieszczaj kluczy w kodzie client-side — do tego użyj OAuth2. VAT 23% i inne wartości domyślne dla Polska są wnioskowane ze scope klucza, ale nadpisywalne per żądanie polem country.
Jak to zintegrować — OAuth2 z PKCE (dostęp delegowany)
Dla aplikacji end-user (mobile, SPA, portale partnerskie) używaj OAuth2 authorisation code z PKCE (S256). Autoryzacja na https://auth.corpmerch.com/oauth2/authorize, wymień code na access token (1 godz.) i refresh token (30 dni, rotujący przy użyciu). Zakresy w paradygmacie najmniejszych uprawnień: orders.read, orders.write, invoices.read itd. Refresh tokeny są device-bound; theft detection unieważnia rodzinę przy wykrytym ponownym użyciu.
Eksploatacja i przypadki brzegowe — mTLS (tenant o podwyższonym bezpieczeństwie)
Klienci enterprise mogą wymagać mTLS obok bearer. Wgraj certyfikat klienta (PEM, RSA 2048 lub ECDSA P-256) w dashboardzie lub przez Trust API. Terminujemy mTLS na edge w Warszawa, walidujemy łańcuch i SAN względem konfiguracji tenantu i dopiero wtedy przyjmujemy żądanie. Rotacja cert przez parę primary/secondary. Uwierzytelnianie do Krajowy System e-Faktur (KSeF) idzie po naszej stronie z naszymi danymi — twój mTLS dotyczy wyłącznie API Corp-Merch.
FAQ
Klucz czy OAuth — kiedy?
Server-to-server w twoim DC lub VPC: API key. Delegacja end-user (mobile, portale partnerów): OAuth2 PKCE. Setupy mieszane używają obu.
Jak rotować klucz?
Wygeneruj nowy klucz równolegle, wdroż, potem unieważnij stary po 24h overlap. Dashboard pokazuje last-used timestamps.
mTLS standard czy płatny?
W tier Enterprise; add-on na Pro. Cert self-signed akceptowane z manual pinning; preferowane CA publiczne.
Wygaśnięcie tokenów?
Access token 1 godz.; refresh token 30 dni, rotujący przy użyciu, z theft detection.
A uwierzytelnianie do KSeF?
KSeF to kanał downstream — uwierzytelniamy się tam w twoim imieniu naszymi danymi. Routing VAT 23% jest transparentny.