REST API authentication for Poland
Bearer keys, OAuth2 PKCE and mTLS — REST API authentication for Poland customers.
Architecture — API keys (server-to-server)
Generate API keys in the dashboard, scoped to country (Poland) and role (read-only, orders, invoices, admin). Pass via Authorization: Bearer cm_live_… over TLS 1.3. Keys are prefixed for environment (cm_live_, cm_test_) and rotated with zero downtime via a 24-hour overlap window. Never embed keys in client-side code — use OAuth2 for those flows. VAT 23% and other Poland country defaults are inferred from the key scope but can be overridden per request via the country field.
How to wire it up — OAuth2 + PKCE (delegated access)
For end-user apps (mobile, SPA, partner portals) use OAuth2 authorisation code flow with PKCE (S256). Authorise at https://auth.corpmerch.com/oauth2/authorize, exchange the code for an access token (1 hour) and refresh token (30 days, rotated on use). Scopes follow least-privilege: orders.read, orders.write, invoices.read, etc. Refresh tokens are device-bound; theft detection auto-invalidates the family on detected reuse.
Operations and edge cases — mTLS (high-security tenants)
Enterprise customers can require mutual TLS in addition to bearer auth. Upload your client certificate (PEM, RSA 2048 or ECDSA P-256) via the dashboard or provision it via the Trust API. We terminate mTLS at our edge in Warszawa, validate certificate chain and SAN against your tenant config, and only then accept the request. Cert rotation supported via a primary/secondary pair. Krajowy System e-Faktur (KSeF) channel auth runs on our side using our credentials — your mTLS is for the Corp-Merch API only.
FAQ
Key vs OAuth — when?
Server-to-server inside your data centre or VPC: API key. End-user delegation (mobile, partner portals): OAuth2 PKCE. Mixed setups commonly use both.
How do I rotate a key?
Generate a new key alongside the old, deploy, then revoke the old after the 24h overlap window. Dashboard shows last-used timestamps to confirm.
Is mTLS standard or paid?
Included on Enterprise tier; available as an add-on for Pro tier. Self-signed certs accepted with manual pinning; public CAs preferred.
Token expiry?
Access tokens 1 hour; refresh tokens 30 days, rotated on use, with theft detection.
Where is KSeF authentication?
KSeF is a downstream invoice channel — we authenticate to it on your behalf using our credentials, not yours. VAT 23% routing happens transparently.