Авторизация: один заголовок, один ключ

У Supply API ровно один креденшл и ровно один способ его передать. Нет вызова логина, нет обмена токенов, нет цикла обновления — ключ, выданный при подключении, это и есть вся авторизация.

Заголовок

Отправляйте X-Api-Key в каждом запросе под /b2b/:

GET /b2b/catalog/games HTTP/1.1
Host: api.gamecore-api.tech
X-Api-Key: gc_live_…

Authorization: Bearer … в этом API не читается нигде — запрос, в котором есть только bearer-токен, считается неавторизованным. Формы «ключ в query-параметре» тоже нет, и это намеренно: ключи в URL оседают в логах прокси, истории браузера и заголовке Referer.

Как выглядит ключ

Ключ — это префикс плюс 48 шестнадцатеричных символов:

Два свойства этой строки стоит знать до того, как вы построите вокруг неё свою обвязку:

• Префикс мы никогда не разбираем. Ключ ищется по хэшу всей строки целиком. Различие «боевой/тестовый» — свойство записи аккаунта, а не символов, поэтому не выводите поведение из совпадения с gc_live_.
• Это секрет на предъявителя в самом буквальном смысле. Кто держит ключ, тот тратит ваш баланс. Держите его в серверном хранилище секретов: не во фронтовом бандле, не в репозитории, не в тикете поддержки. Если ключ утёк — скажите нам, мы его перевыпустим; префикс при ротации сохраняется.

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

Боевые и тестовые ключи

Это самое дорогое из возможных заблуждений на этой странице, поэтому оно стоит первым. Разделение test/live на платформе действительно есть, но оно закрывает другую поверхность — отдельный набор симуляционных эндпоинтов вне /b2b/, которым оптовые партнёры не пользуются.

Практическое следствие для интеграции: бесплатно прогнать путь заказа не получится. Что можно сделать, ничего не потратив:

• Полностью отладить каталожную часть на своём ключе. Чтения бесплатны и не ограничены ничем, кроме лимита запросов.
• Прогнать код заказа на дешёвом SKU — и оставить заказ себе, он будет доставлен.
• Предупредить нас перед нагрузочным тестом. Нам проще расширить вам лимит, чем смотреть, как всплеск превращается в 429.

Когда приходит 401

{ "error": "Unauthorized", "message": "Invalid or missing API key" }

Одно тело на пять разных причин, и это сделано намеренно — атакующий, перебирающий ключи, не должен узнавать разницу:

• Заголовка X-Api-Key нет вообще.
• Ключа не существует или он деактивирован.
• Срок действия ключа истёк.
• Аккаунт за ключом неактивен.
• В запросе пришёл Origin вне белого списка доменов, настроенного для этого ключа.

Обратите внимание на конверт: { error, message }, без поля success. У бизнес-ошибок конверт другой — { success: false, error }, — поэтому клиент, который ветвится по response.success, получит undefined ровно на том отказе, с которым столкнётся первым. Ветвитесь по HTTP-статусу.

Когда приходит 403

Два разных тела и два разных способа починки:

{ "error": "Forbidden", "message": "This endpoint is only available for B2B API partners" }

Ключ верный, но аккаунт за ним — витринный, а не оптовый. Со своей стороны вы сделать ничего не можете: напишите нам, мы переключим.

{ "error": "Forbidden", "message": "This API key is not authorized for this endpoint" }

У ключа область видимости «только публичное чтение». Оптовые ключи всегда выдаются с полной областью, так что этот ответ означает, что в вашей конфигурации подхватился не тот ключ.

Заголовки лимитов

Почти каждый ответ, включая успешные, несёт остаток вашего бюджета:

У слова «почти» есть одно известное исключение, и оно устроено так намеренно: проверка Origin (защита от CSRF) стоит раньше счётчика лимитов, поэтому пишущий запрос, отклонённый с 403 Forbidden: Origin not allowed, до кода, который выставляет эти заголовки, просто не доходит — и приходит без них. Считайте заголовки необязательными и ветвитесь сначала по статусу: отсутствие X-RateLimit-Remaining не означает, что бюджет исчерпан.

Бюджет по умолчанию — 500 запросов в минуту, и считается он по IP клиента, а не по ключу. При превышении приходит 429 с заголовком Retry-After и телом, в котором есть code: "RATE_LIMITED" и retryAfter в секундах. Если вашему трафику честно нужно больше — например, ночная полная синхронизация каталога, — договоритесь с нами, а не размазывайте нагрузку по IP. Подробности и советы по бэкоффу — на странице Идемпотентность и ошибки.

Никогда не вызывайте этот API из браузера

Это не вкусовое предпочтение — запрет держат два механизма. Ключ, уехавший в браузер, — это опубликованный ключ; а пишущий запрос, пришедший с Origin вне белого списка, отбивается с телом {"success": false, "error": "Forbidden: Origin not allowed"}. Ходите в /b2b/ со своего бэкенда, а фронтенду отдавайте собственные эндпоинты.

Почему не OAuth

Законный вопрос, если вы интегрировали другие оптовые API, поэтому вот честный ответ, а не пожатие плечами.

OAuth решает задачу делегированного доступа: пользователь разрешает приложению действовать от своего имени, а scope'ы и короткоживущие токены избавляют приложение от хранения пароля пользователя. В этом API делегировать не от кого. Есть ваша компания, ваш баланс и ваш сервер. Единственная сторона, которая может что-то разрешить, — это вы сами себе.

Прикрутить сверху обмен токенов означало бы добавить лишний round trip, кэш токенов, отказ на обновлении токена и отказ на расхождении часов — и купить ровно одно реальное свойство: более короткую жизнь креденшла. Мы даём его иначе: ключу можно поставить срок, привязать белый список доменов и перевыпустить по запросу, а все вызовы идут по TLS к одному хосту. Если вашему security review нужен конкретный контроль (белый список IP, ротация по расписанию, отдельный ключ для стейджингового трафика) — попросите: это настройки аккаунта, а не смена протокола.

Интерактивный референс

Документация — вот эти страницы. Дополнительно, как удобство для партнёров, есть сгенерированный просматриваемый OpenAPI-референс по адресу api.gamecore-api.tech/reference?key=…: он рендерит машиночитаемую спецификацию всего API и позволяет отправлять запросы прямо из браузера.

Две оговорки, обе настоящие:

• Ему нужен валидный ключ в URL. То есть живой секрет попадает в историю браузера и в любой прокси на пути. Открывайте его с машины, которую контролируете, и лучше тем ключом, который не жалко перевыпустить.
• Он описывает всю платформу, а не только оптовую поверхность, поэтому покажет эндпоинты, до которых ваш ключ не дотянется. Там, где он и эти страницы расходятся, эти страницы сверялись с кодом позже.

Голый адрес api.gamecore-api.tech/docs закрыт по той же причине и публичной страницей не является.

Перед запуском

• Ключ лежит в серверном хранилище секретов и не попадает ни в один клиентский бандл.
• Клиент ветвится по HTTP-статусу, а не по полю success, которого в ошибках авторизации нет.
• На 401 и 403 заведены разные алерты: первое — проблема с креденшлом, второе — с аккаунтом.
• X-RateLimit-Remaining пишется в логи, чтобы про потолок вы узнали раньше, чем упрётесь в него.
• Никто в команде не считает, что ключом gc_test_ можно безопасно постучать в /b2b/orders.