Аутентификация

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

mbs_AbCdEf...XyZ123

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

Выпуск ключа

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

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

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

X-API-Key: mbs_AbCdEf...

или

Authorization: Bearer mbs_AbCdEf...

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

Примеры

cURL

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

Node.js (fetch)

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

Python (requests)

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

Go (net/http)

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

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

curl "https://capybara.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, секреты CI или менеджер вроде Vault.
• Если ключ утёк — отзовите его и выпустите новый. Все запросы со старым ключом мгновенно перестанут работать.
• Ключи с scope write могут отправлять сообщения от имени бота — относитесь к ним как к токену бота.

Когда использовать JWT кабинета

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

REST API v1 (/api/v1/...) только на API-ключах. Не пытайтесь подавать туда JWT — получите 401.

Коды ответа аутентификации

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