Аутентификация REST API в Польше
Bearer-ключи, OAuth2 PKCE и mTLS — аутентификация REST API для клиентов в Польше.
Архитектура — API-ключи (server-to-server)
Создавайте API-ключи в дашборде с областью по стране (Польша) и роли (read-only, заказы, счета, admin). Передавайте через Authorization: Bearer cm_live_… по TLS 1.3. Префиксы по окружению (cm_live_, cm_test_), ротация без даунтайма с 24-часовым окном перекрытия. Никогда не встраивайте ключи в client-side код — для таких потоков используйте OAuth2. VAT 23% и другие значения по умолчанию для рынка Польши выводятся из области ключа, но переопределяются полем country в запросе.
Как подключить — OAuth2 с PKCE (делегированный доступ)
Для приложений конечных пользователей (мобайл, SPA, партнёрские порталы) используйте OAuth2 authorisation code с PKCE (S256). Авторизация на https://auth.corpmerch.com/oauth2/authorize, обмен code на access token (1 час) и refresh token (30 дней, ротация при использовании). Области по принципу минимальных привилегий: orders.read, orders.write, invoices.read и т. д. Refresh-токены привязаны к устройству; детекция кражи инвалидирует семью при обнаружении повторного использования.
Эксплуатация и пограничные случаи — mTLS (тенанты с повышенной безопасностью)
Корпоративные клиенты могут потребовать mTLS поверх bearer. Загрузите клиентский сертификат (PEM, RSA 2048 или ECDSA P-256) в дашборде или через Trust API. Мы терминируем mTLS на edge в Варшаве, проверяем цепочку и SAN на соответствие конфигурации тенанта и только затем принимаем запрос. Ротация сертификатов через пару primary/secondary. Аутентификация в Krajowy System e-Faktur (KSeF) идёт на нашей стороне нашими учётными данными — ваш mTLS относится только к API Corp-Merch.
Частые вопросы
Key или OAuth — когда?
Server-to-server внутри вашего DC или VPC: API-ключ. Делегирование конечному пользователю (мобайл, партнёрские порталы): OAuth2 PKCE. Смешанные сценарии используют оба варианта.
Как ротировать ключ?
Сгенерируйте новый ключ параллельно, задеплойте, затем отзовите старый через 24-часовое окно перекрытия. В дашборде есть last-used timestamps для подтверждения.
mTLS — стандарт или платно?
Включено в Enterprise; add-on на Pro. Self-signed принимаются с ручным pinning; предпочтительны публичные CA.
Срок жизни токенов?
Access token — 1 час; refresh token — 30 дней с ротацией при использовании и детекцией кражи.
А аутентификация в KSeF?
KSeF — downstream-канал; мы аутентифицируемся в нём от вашего имени нашими учётными данными. Маршрутизация VAT 23% прозрачна.