# API-ключи Три вида учётных данных, три модели угроз. ## `pk_` — Publishable - Предназначен для отправки в браузер. Передаётся как заголовок `X-Client-ID` на каждом подписанном B2B-запросе, также встроен в бандл SDK для клиентских открытий checkout. - Может идентифицировать ваш аккаунт; не может создавать сессии, читать данные других мерчантов или запускать что-то деструктивное. - Утечка publishable-ключа — **низкая** угроза. ## `sk_` — Secret (HMAC-ключ подписи) - Ключ подписи HMAC-SHA256 для всех B2B API-вызовов — см. [Аутентификация](https://docs.infraio.xyz/ru/api-reference/authentication). - Никогда не путешествует по сети. Только его подпись per-request. Поэтому беспокоиться о утечках нужно только на *уровне хранения* (env vars, git, логи), а не на транспортном уровне. - Только серверный. Никогда не должен появляться в браузерном бандле, публичном репо, скриншоте или сообщении в чате. - Утечка секрета — **высокая** угроза. ## `whsec_` — Секрет подписи webhook - Используется для проверки подписи на **входящих** доставках webhook от нас к вашему серверу. См. [Проверка подписи](https://docs.infraio.xyz/ru/webhooks/signature-verification). - Отдельный для каждого webhook-endpoint'а — если у вас 3 зарегистрированных endpoint'а, у вас 3 разных секрета `whsec_`. Окружение закодировано в префиксе: `whsec_live_…` / `whsec_test_…`. - Только серверный. Как и `sk_`, никогда не путешествует по сети — используется только для проверки HMAC локально. - **У ротации есть 24-часовое grace-окно.** Нажмите Rotate, и предыдущий секрет остаётся принимаемым 24 часа наряду с новым (доставки несут и `X-Signature`, и `X-Signature-Prev`), чтобы вы могли переразвернуть verifier без удержания трафика. - **Reveal-existing-secret** доступен, защищён свежим 2FA и записывается в журнал аудита — для случая, когда секрет потерян и ротация неприемлема. Дефолтная позиция панели — «ротировать, не раскрывать». - Утечка webhook-секрета позволяет атакующему подделывать события на ваш URL. **Средне-высокая угроза** в зависимости от того, насколько вы доверяете payload'у события. ## Scope'ы Secret-ключи scope'ятся. Панель позволяет выпускать ключи с одним из этих наборов scope'ов: | Scope | Может делать | Используется для | | --- | --- | --- | | `read` | Чтение списков и единичных заказов, сессий, возвратов, балансов | Read-only интеграции (аналитика, BI) | | `write_order` | Всё `read` + создание сессий, создание заказов, отмена заказов | Backend витрины | | `write_refund` | Всё `read` + создание возвратов, пометка возвратов исполненными | Инструменты поддержки клиентов | | `webhook_manage` | Всё `read` + управление webhook-endpoint'ами | DevOps-тулинг | Ключ default-mint «full access» получает все четыре. Выпуск per-purpose ключей всё равно хорошая практика, потому что это документирует намерение, но прочтите оговорку ниже, прежде чем рассматривать scope как границу безопасности. > **Warning:** > > **Scope'ы пока не применяются.** Утёкший ключ `sk_` *любого* scope'а > может вызвать *любой* endpoint `/b2b/v1/*` для вашего мерчанта. Ключу > `read` не запрещено создавать возврат. Узкие scope'ы пока **не** > ограничивают ущерб от утечки: для планирования безопасности считайте > каждый secret-ключ ключом с полным доступом и полагайтесь на быструю > ротацию и отзыв (ниже), чтобы сдержать утечку. ## Ротация 1. **Сгенерируйте новый ключ.** Панель → **Developers → API keys** → **+ Add key**. Выберите scope. Панель отображает секрет **один раз** — сохраните его сразу. 2. **Прокатите env vars** на новое значение во всех окружениях. Разверните. 3. **Проверьте трафик.** Панель показывает счётчики запросов per-ключ в реальном времени. Подождите, пока счётчик старого ключа упадёт до нуля. 4. **Отзовите старый ключ.** Тот же экран → меню kebab → **Revoke**. > **Warning:** > > Сегодня **нет автоматического окна перекрытия** — как только вы > отзываете ключ, любой in-flight запрос, подписанный им, получает > `401`. Планируйте ротацию соответственно: разверните новый ключ > первым, дренируйте трафик со старого, затем отзывайте. ## Экстренный отзыв Если ключ утёк (в истории git, в публичном бандле, в логированном стек-трейсе, в pen-test отчёте партнёра) — отзовите его немедленно, даже ценой нескольких упавших запросов. Лучше упасть громко, чем позволить атакующему держать валидный credential. Шаги: 1. **Панель → Developers → API keys → [ключ] → Revoke now.** Эффект мгновенный; grace-периода нет. 2. Выпустите замену и разверните. 3. Проверьте недавнюю активность — панель показывает последние 30 дней запросов per-ключ с IP и затронутыми endpoint'ами. Если вы подозреваете, что брешь шире одного ключа, обратитесь к contact@lartech.xyz, чтобы: - Получить полный экспорт журнала аудита для вашего мерчантского аккаунта - Ротировать webhook-секреты массово - Опционально заморозить аккаунт на время расследования ## Лучшие практики хранения - **Только env vars.** Никогда не коммитьте секреты в git, даже в `.env.example` со словами «REPLACE ME». - **Per-environment ключи.** Разные `sk_test_…` и `sk_live_…` для dev/staging/prod, источники из вашего secrets manager'а (AWS Secrets Manager, Vault, Doppler, …). - **Ограничьте доступ к env vars.** В Kubernetes монтируйте как `Secret`, не `ConfigMap`. В Vercel/Netlify используйте scope environment-переменных, а не project-wide global'ы. - **Не логируйте запросы с телами.** Даже при отладке — ваша HMAC-подпись в `X-Signature` одноразовая, но ваш бизнес-payload может содержать PII. ## Что НЕ поддерживается сегодня - **IP-allowlisting** для secret-ключей. - **OAuth-стиль scope'ируемые per-user токены.** Текущая модель ключей per-merchant, не per-user. - **Автоматическая ротация ключей** (например, еженедельная принудительная ротация платформой). Ротация выполняется вручную. ## Что дальше - [Аутентификация](https://docs.infraio.xyz/ru/api-reference/authentication) — точный алгоритм подписи для B2B-вызовов. - [Webhooks → Проверка подписи](https://docs.infraio.xyz/ru/webhooks/signature-verification) — как `whsec_` используется на входящих событиях.