API KEYBD

Коротко

Все запросы идут на один адрес и авторизуются ключом, который вы создаёте в личном кабинете. Ключ работает только с тех IP-адресов, которые к нему привязаны. Ответы и ошибки — всегда JSON.

Что нужно знать сразу

• До 5 активных ключей на аккаунт.
• До 10 IP-адресов на ключ.
• У каждого IP есть пометка — она обязательна, чтобы было видно, чей это сервер.
• 120 запросов в минуту делятся на весь аккаунт, а не на каждый ключ.
• Секрет ключа показывается один раз — при создании.
• Отозванный ключ перестаёт работать сразу, без задержки.

Ключ и доступ

Ключ передаётся в заголовке X-Api-Key. Сессионный токен личного кабинета сюда не подходит: на запрос без ключа API отвечает 401 api_key_required.

X-Api-Key: kbd_live_WiILzST_hHX6IZj7pJqRGegCG5KEjD0gXJuqM0ZUw0Q

В списке ключей в кабинете виден только публичный префикс вида kbd_live_WiILzST. Полная строка есть только у вас — восстановить её нельзя, потерянный ключ отзывают и создают новый.

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

1. 1Откройте в кабинете «Настройки → API».
2. 2Нажмите «Создать ключ» и дайте ему имя — по нему потом будет понятно, где он используется.
3. 3Добавьте IP-адреса серверов, с которых пойдут запросы.
4. 4Скопируйте секрет — после закрытия окна он больше не покажется.

Разрешённые IP

Ключ проходит только с адресов, перечисленных в его списке. Пока список пуст, ключ не выполнит ни одного запроса.

• Только конкретный IPv4 или IPv6 — подсети (CIDR) и доменные имена не принимаются.
• Пометка обязательна, от 1 до 100 символов: «API 1», «Склад».
• До 10 адресов на ключ, повторный адрес отклоняется.
• Запрос с чужого адреса получает 403 api_key_ip_not_allowed.

Лимиты запросов

По умолчанию 120 запросов в минуту. Лимит общий на аккаунт: несколько ключей расходуют одну и ту же квоту, а не по квоте каждый.

Персональный лимит выставляется по договорённости — тогда в заголовках будет ваше значение вместо 120.

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

Превышение лимита — 429 rate_limited. Дождитесь времени из X-RateLimit-Reset и повторите запрос.

Методы

Пока открыты две ручки. Список будет пополняться — формат доступа и ответов останется прежним.

curl https://api.keybd.store/api/v1/open/health \
  -H "X-Api-Key: kbd_live_WiILzST_hHX6IZj7pJqRGegCG5KEjD0gXJuqM0ZUw0Q"

{ "status": "ok" }

curl https://api.keybd.store/api/v1/open/balance \
  -H "X-Api-Key: kbd_live_WiILzST_hHX6IZj7pJqRGegCG5KEjD0gXJuqM0ZUw0Q"

{ "balance": "125.5000" }

Ошибки

Любой неуспешный ответ приходит в одном формате: поле «error» — стабильный код, по которому ветвится ваш код, «message» — готовый текст на двух языках.

{
  "error": "api_key_ip_not_allowed",
  "message": {
    "en": "This IP is not on the key allowlist",
    "ru": "Этот IP не в списке разрешённых для ключа"
  }
}