Перейти к основному содержимому

Ключи и авторизация

Каждый запрос к API подписывается ключом вида tbx_… (44 символа). Ключ определяет, какие продукты вам доступны, какими способами (REST, MCP) и сколько запросов можно сделать.

Как получить ключ​

Ключи выдаёт команда Tapbox Стат под ваши задачи: напишите нам через «Обратную связь» на сайте, и мы подключим нужные продукты и лимиты.

Если собираетесь подключаться через claude.ai, пришлите вместе с запросом свой MAX ID — он есть в профиле, в блоке «Настройки», строка «Мой MAX ID». В claude.ai можно выбрать только ключ, привязанный к вашему аккаунту.

Если при выдаче ключ привязан к вашему аккаунту, он появится в профиле — там видны маска ключа, подключённые продукты, расход за сегодня и за месяц и дата последнего вызова. Там же ключ можно отозвать.

Ключ показывается один раз

Целиком ключ виден только в момент выпуска. Мы храним не сам ключ, а его хэш, поэтому восстановить потерянный ключ нельзя — только отозвать и выпустить новый.

REST-API: заголовок X-API-Key​

curl -H "X-API-Key: tbx_ваш_ключ" "https://beta.stat.tapbox.ru/api/channels/stats"

Допускается и параметр ?api_key=tbx_ваш_ключ в адресе, но лучше им не пользоваться: адреса с параметрами оседают в логах и истории браузера.

Чтобы REST-запросы работали, у ключа должен быть включён доступ «REST-API». Если он выключен, сервер ответит 401.

MCP: заголовок Authorization: Bearer​

MCP-сервер https://beta.stat.tapbox.ru/api/mcp принимает тот же ключ в заголовке:

Authorization: Bearer tbx_ваш_ключ

Подробности и готовые настройки клиентов — на странице MCP для ИИ-агентов.

OAuth: подключение без ключа в настройках​

Клиенты с поддержкой OAuth — claude.ai, Claude Desktop, Claude Code — подключаются к MCP-серверу через вход в Tapbox Стат. Пользователь входит через MAX и выбирает один из своих ключей, а приложение получает токен доступа, привязанный к этому ключу: с теми же продуктами, лимитами и квотой. Сам ключ приложение не видит.

  • Без ключа сервер отвечает 401 с заголовком WWW-Authenticate, в котором указан адрес метаданных: https://beta.stat.tapbox.ru/.well-known/oauth-protected-resource/api/mcp.
  • Метаданные сервера авторизации — https://beta.stat.tapbox.ru/.well-known/oauth-authorization-server.
  • Поддерживаются динамическая регистрация клиентов (RFC 7591), код авторизации с PKCE S256 и обновление токенов с ротацией.
  • Токен доступа живёт час, токен обновления — 90 дней. Токены работают только в MCP, для REST-API нужен ключ.

Подключённые приложения видны в профиле, там же их можно отключить.

Как хранить ключ​

  • Держите ключ в переменной окружения или менеджере секретов, а не в коде. Например, TAPBOX_API_TOKEN.
  • Не публикуйте ключ в репозиториях, тикетах и переписке с нейросетью.
  • Не вызывайте API с ключом из браузера пользователя: ключ окажется в открытом коде страницы. Ходите в API со своего сервера.
  • Если ключ мог утечь — отзовите его в профиле и попросите новый. Отзыв действует сразу, в пределах 30 секунд.

Ответ при ошибке авторизации​

{
  "error": "unauthorized",
  "hint": "API access requires a key"
}

Сервер отвечает 401, если ключ не передан, не найден, отозван или у него выключен REST. Коды остальных ошибок — на странице Продукты, лимиты и ошибки.