Аутентификация в API Salebot: ключи, токены и безопасность

Шаг 1: Генерация ключа

1. Войдите в личный кабинет Salebot
2. Перейдите: Настройки → API → Ключи доступа
3. Нажмите "Создать новый ключ"
4. Укажите название (например, "Сервис аналитики") и выберите права:
   • Чтение — только получение данных
   • Запись — создание и изменение данных
   • Управление — удаление, настройка
5. Нажмите "Создать"
6. Скопируйте ключ (он покажется только один раз!)

Важно: Ключ выглядит как случайная строка из 64 символов, например: sb_live_abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890

Шаг 2: Использование в запросах

Добавьте заголовок X-API-Key в каждый HTTP-запрос:

GET /v1/bots HTTP/1.1
Host: api.salebot.pro
X-API-Key: sb_live_abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890
Content-Type: application/json

Пример с curl:

curl -X GET "https://api.salebot.pro/v1/bots" \
  -H "X-API-Key: ваш_ключ_api" \
  -H "Content-Type: application/json"

Шаг 3: Безопасное хранение

API-ключ — это пароль к вашему аккаунту. Никогда не храните его:

• В коде приложения (особенно в frontend-коде)
• В системах контроля версий (Git)
• В логах приложения
• В открытых репозиториях

Рекомендуется: Хранить ключ в переменных окружения, секретных менеджерах (HashiCorp Vault, AWS Secrets Manager) или в .env файле (который добавлен в .gitignore).

Шаг 1: Регистрация приложения

1. В личном кабинете перейдите: Настройки → API → OAuth-приложения
2. Нажмите "Создать приложение"
3. Заполните данные:
   • Название приложения
   • Описание
   • Redirect URI (куда будет перенаправлен пользователь после авторизации)
   • Права (scopes), которые запрашивает приложение
4. Получите client_id и client_secret

Шаг 2: Авторизация пользователя

Перенаправьте пользователя на страницу авторизации Salebot:

https://api.salebot.pro/oauth/authorize?
  response_type=code&
  client_id=ВАШ_CLIENT_ID&
  redirect_uri=ВАШ_REDIRECT_URI&
  scope=bot:read bot:write&
  state=случайная_строка

Пользователь увидит экран с запросом разрешений. После согласия он будет перенаправлен на ваш redirect_uri с параметром code.

Шаг 3: Получение токена доступа

Обменяйте код на токен доступа:

POST /oauth/token HTTP/1.1
Host: api.salebot.pro
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&
code=ПОЛУЧЕННЫЙ_КОД&
redirect_uri=ВАШ_REDIRECT_URI&
client_id=ВАШ_CLIENT_ID&
client_secret=ВАШ_CLIENT_SECRET

В ответ вы получите:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer",
  "expires_in": 86400,
  "refresh_token": "def50200abc...",
  "scope": "bot:read bot:write"
}

Шаг 4: Использование токена

Используйте access_token в заголовке Authorization:

GET /v1/bots HTTP/1.1
Host: api.salebot.pro
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Основные scopes

• bot:read — чтение информации о ботах, диалогах, статистике
• bot:write — создание и изменение ботов, отправка сообщений
• client:read — чтение информации о клиентах
• client:write — создание и изменение клиентов
• analytics:read — чтение аналитики
• webhook:manage — управление вебхуками
• * — все права (администратор)

Принцип минимальных привилегий: Давайте только те права, которые действительно нужны. Если приложению нужно только читать статистику, дайте только analytics:read.

Коды ошибок

• 401 Unauthorized — неверный или отсутствующий API-ключ/token
• 403 Forbidden — у ключа недостаточно прав для этого действия
• 429 Too Many Requests — превышен лимит запросов (rate limiting)
• 400 Bad Request — неверный формат запроса (например, отсутствует обязательный заголовок)

Пример ответа с ошибкой

{
  "error": {
    "code": "authentication_failed",
    "message": "Invalid API key",
    "details": "The provided API key is either expired or invalid"
  }
}

Лимиты по тарифам

• Бесплатный: 100 запросов в минуту
• Старт: 500 запросов в минуту
• Профессиональный: 2000 запросов в минуту
• Корпоративный: 10000 запросов в минуту

Лимиты считаются по аккаунту, а не по ключу. Все ключи одного аккаунта делят общий лимит.

Как обрабатывать rate limiting

При получении ошибки 429:

1. Подождите перед повторным запросом (рекомендуется экспоненциальная backoff-стратегия)
2. Проверьте заголовки ответа:
   • X-RateLimit-Limit — общий лимит
   • X-RateLimit-Remaining — оставшиеся запросы
   • X-RateLimit-Reset — время сброса лимита (Unix timestamp)
3. Оптимизируйте приложение: кэшируйте ответы, объединяйте запросы, используйте вебхуки вместо polling