Авторизация

Открытый API авторизуется по ключу API — статической строкой, начинающейся с префикса mbs_.

mbs_AbCdEf...XyZ123

Ключ показывается один раз при выпуске. Дальше в кабинете виден только префикс (mbs_AbCdEf...).

Выпуск ключа

1. Настройки → API → Создать ключ.
2. Укажите имя (например, crm-export) — для вас, чтобы помнить, где он живёт.
3. Выберите разрешения:
   • read — только чтение (статистика, контакты, сообщения);
   • write — отправка (рассылки, одиночные сообщения);
   • оба — для интеграций с двусторонним обменом.
4. По желанию — expires_at. После этой даты ключ перестанет работать.
5. Создать. Скопируйте ключ. После закрытия окна восстановить его нельзя — выпустите новый.

Использование

Ключ передаётся в одном из двух заголовков:

X-API-Key: mbs_AbCdEf...

или

Authorization: Bearer mbs_AbCdEf...

Поведение одинаковое.

Примеры

cURL

curl "https://app.maxbotstat.ru/api/v1/me" \
     -H "X-API-Key: $MBS_KEY"

Node.js

const r = await fetch('https://app.maxbotstat.ru/api/v1/me', {
  headers: { 'X-API-Key': process.env.MBS_KEY },
})
console.log(await r.json())

Python

import os, requests
r = requests.get(
    'https://app.maxbotstat.ru/api/v1/me',
    headers={'X-API-Key': os.environ['MBS_KEY']},
    timeout=10,
)
print(r.json())

Go

req, _ := http.NewRequest("GET", "https://app.maxbotstat.ru/api/v1/me", nil)
req.Header.Set("X-API-Key", os.Getenv("MBS_KEY"))
resp, err := http.DefaultClient.Do(req)

Проверить владельца ключа

curl "https://app.maxbotstat.ru/api/v1/me" \
     -H "X-API-Key: $MBS_KEY"

{
  "id": "8a34...",
  "email": "user@example.com",
  "role": "user",
  "plan_key": "pro",
  "plan_until": "2026-06-01T00:00:00Z",
  "created_at": "2025-09-12T08:21:00Z",
  "scopes": ["read", "write"]
}

Отзыв ключа

В кабинете: Настройки → API → Отозвать. После отзыва любой запрос с этим ключом получит 401 API-ключ отозван.

Лимиты

• До 20 активных ключей на пользователя. После лимита нужно отозвать старые.
• Срок действия — до 5 лет.
• Префикс mbs_ фиксирован, остальная часть — base64url (32 байта), около 43 знаков.

Безопасность

• Не публикуйте ключ в репозитории. Используйте .env, секреты сборочного конвейера или менеджер вроде Vault.
• Если ключ утёк — отзовите его и выпустите новый. Все запросы со старым ключом мгновенно перестанут работать.
• Ключи с разрешением write могут отправлять сообщения от имени бота — относитесь к ним как к токену бота.

Когда использовать сессионный ключ кабинета

Ваш кабинет использует сессионный ключ, выдаваемый при логине, со сроком 7 дней. Он работает на закрытых методах /api/... (без v1).

Открытый API /api/v1/... — только на ключах API. Сессионный ключ туда не подходит.

Коды ответа авторизации

Код	Сообщение	Что делать
401	API-ключ обязателен	заголовок не пришёл
401	Неверный API-ключ	опечатка или ключ удалён
401	API-ключ отозван	выпустите новый
401	Срок действия API-ключа истёк	продлите или выпустите новый
403	Недостаточно прав: требуется scope "write"	выпустите ключ с нужным разрешением