WooCommerce REST API: безопасная авторизация Consumer Key и Consumer Secret

WooCommerce REST API используют для CRM, ERP, складского учёта, мобильных приложений, выгрузки заказов и серверной автоматизации. Но рабочая интеграция начинается не с первого запроса к /wp-json/wc/v3/, а с правильной модели доступа: какой пользователь владеет ключом, какие операции ему разрешены и где физически хранится Consumer Secret.

Если сделать ключ с максимальными правами и вставить его в публичный JavaScript, интеграция может работать — но это уже серьёзная уязвимость. Ниже разберём безопасный серверный вариант, типовые ошибки 401 и порядок ротации ключей без хаотичной замены настроек.

Что именно авторизует WooCommerce REST API

Официальная документация WooCommerce указывает, что REST API keys создаются для конкретного пользователя WordPress. Доступ через такой ключ подчиняется ролям и capabilities этого пользователя. Если пользователя удалить, связанные с ним API keys перестанут работать.

Это важнее, чем кажется. Ключ не существует отдельно от модели прав WordPress: интеграция получает не абстрактный «доступ к WooCommerce», а возможности выбранной учётной записи плюс уровень самого ключа — Read, Write или Read/Write.

Где создаются Consumer Key и Consumer Secret

В актуальном WooCommerce ключи создаются в WooCommerce → Settings → Advanced → REST API. Для ключа задаются описание, пользователь и уровень доступа. После генерации WooCommerce показывает Consumer Key и Consumer Secret.

Consumer Secret нужно сохранить сразу в защищённом хранилище. Не рассчитывайте, что его можно будет в любой момент снова открыть в админке. Для production-интеграции удобно сразу записать, для какого сервиса создан ключ, кто его владелец и какие права ему нужны.

Выдавайте минимально необходимые права

Если сервис только читает каталог или заказы, ему не нужен Write. Если интеграция обновляет остатки, но не должна управлять пользователями или настройками, стоит отдельно проверить capabilities пользователя, которому выдан ключ.

• Read — для чтения разрешённых ресурсов;
• Write — для операций записи там, где это поддерживается;
• Read/Write — когда интеграции действительно нужны оба направления.

Принцип минимальных прав уменьшает последствия утечки. Один универсальный ключ для CRM, склада, аналитики и тестового скрипта удобен только до первой проблемы.

Авторизация по HTTPS

WooCommerce документирует HTTP Basic Auth для HTTPS: Consumer Key передаётся как username, Consumer Secret — как password. Для серверного curl-проверочного запроса схема выглядит так:

curl https://example.com/wp-json/wc/v3/orders \
  -u 'ck_xxx:cs_xxx'

Такой запрос выполняется только с backend или администраторской машины. Никогда не вставляйте реальные ck_/cs_ в HTML, frontend bundle, публичный Git-репозиторий или пример в документации проекта.

Почему ключи нельзя использовать во frontend

Любой секрет, отправленный браузеру, фактически становится доступен пользователю страницы. Его можно увидеть в DevTools, исходном коде, network request или собранном JavaScript.

Если отдельному frontend нужен каталог, корзина и checkout, для покупательских сценариев у WooCommerce есть Store API. Административный REST API с Consumer Secret предназначен для доверенного серверного окружения.

Не путайте WooCommerce keys и WordPress Application Passwords

WordPress поддерживает Application Passwords для программного доступа к REST API. WooCommerce REST API при этом имеет собственную систему Consumer Key/Secret. Выбор зависит от endpoint, клиента и архитектуры интеграции.

Отдельно механизм WordPress я разбирал в статье про Application Passwords. Не стоит смешивать два способа авторизации в одном клиенте без необходимости.

Что означает 401 Unauthorized

Официальная документация WooCommerce рекомендует при 401 проверить корректность ключей, права пользователя и способ передачи Authorization. На практике диагностику удобно вести по цепочке.

1. Проверить, что используется правильный магазин и endpoint /wp-json/wc/v3/.
2. Проверить, что ключ не отозван.
3. Убедиться, что связанный пользователь существует и имеет доступ к нужному ресурсу.
4. Проверить уровень Read/Write ключа.
5. Сделать минимальный запрос напрямую, минуя CRM или промежуточный сервис.
6. Проверить reverse proxy/FastCGI, если Authorization теряется по пути.

Consumer key is missing при правильных данных

WooCommerce отдельно описывает ситуацию, когда сервер не передаёт заголовок Authorization в PHP. Тогда API сообщает, что consumer key отсутствует, хотя клиент его отправил.

Это уже не причина генерировать десятый новый ключ. Нужно проверить Nginx/Apache/FastCGI, прокси и фактические заголовки на стороне приложения. Query-string authentication существует как совместимый вариант для некоторых серверов, но секрет в URL легче случайно записать в access log, историю или мониторинг, поэтому сначала лучше исправить нормальную передачу Authorization.

Не логируйте секреты

Интеграционный лог должен содержать endpoint, HTTP method, код ответа, безопасный идентификатор операции и короткое описание ошибки. Полный Authorization header, Consumer Secret и URL с секретными query parameters в журнале не нужны.

Особенно проверьте error reporting HTTP-клиента: некоторые библиотеки при исключении печатают весь request config. Перед отправкой в Sentry, Telegram или общий log секретные поля нужно маскировать.

Один сервис — один ключ

Раздельные ключи упрощают аудит и отзыв доступа. Если перестала использоваться старая CRM, можно отозвать только её ключ, не ломая склад и отчётность. По описанию ключа в админке также понятнее, кто им пользуется.

Для сложной связки WooCommerce → CRM полезно отдельно проектировать доставку событий, idempotency и retry. Это разобрано в материале о надёжных WooCommerce webhooks.

Как ротировать ключ без остановки интеграции

1. Создать новый ключ для того же технического пользователя или заранее подготовленной сервисной учётной записи.
2. Сохранить новый secret в secret manager или защищённых переменных окружения.
3. Переключить один тестовый запрос.
4. Проверить чтение и запись только тех операций, которые реально использует сервис.
5. Переключить production-клиент.
6. Убедиться по логам, что старый ключ больше не используется.
7. Отозвать старый ключ.

Не удаляйте старый ключ до подтверждения нового. Иначе обычная ошибка конфигурации превратится в простой обмена.

Хранение секретов

На VPS ключи обычно хранят в переменных окружения, закрытом конфигурационном файле вне public web root или secret storage платформы. В CI/CD — в GitHub Actions Secrets или аналогичном защищённом хранилище. В репозиторий коммитится только имя переменной, а не значение.

WC_URL=https://shop.example
WC_CONSUMER_KEY=...
WC_CONSUMER_SECRET=...

Файл с реальными значениями должен быть исключён из Git и иметь минимально необходимые права на чтение.

Проверяйте не только GET

Успешный список заказов ещё не доказывает, что интеграция готова. Если сервис должен менять статусы, остатки или метаданные, протестируйте именно эти разрешённые операции на staging или тестовом объекте.

При этом не делайте destructive-тесты на реальном заказе без плана отката. Для записи полезно создать отдельный тестовый товар/заказ и зафиксировать ожидаемое состояние до и после API-вызова.

Чек-лист production-интеграции

• REST API работает по HTTPS;
• ключ принадлежит понятному пользователю WordPress;
• выданы минимальные необходимые права;
• Consumer Secret отсутствует во frontend и Git;
• Authorization header проходит через proxy/FastCGI;
• логи маскируют секреты;
• у каждого внешнего сервиса свой ключ;
• есть порядок ротации и отзыва;
• ошибки 401/403 различаются и логируются;
• production-проверка выполняется контролируемо.

Когда нужна доработка интеграции

Если CRM периодически получает 401, склад обновляет не те товары или API работает только при передаче ключа в URL, проблема обычно находится в архитектуре авторизации, правах, proxy или клиентском коде. В A.S Groups можно заказать интеграцию CRM с сайтом или диагностику существующего WooCommerce API-обмена.

Для оценки достаточно описать внешний сервис, нужные операции Read/Write, текущий endpoint и безопасно передать текст ошибки без секретных ключей. Связаться можно через страницу контактов.

Официальные источники

• WooCommerce REST API Authentication
• WooCommerce REST API documentation
• WooCommerce REST API v3