IBA Platform logo

Ошибки авторизации 401 и 403

Что делать при ошибках 401 Unauthorized и 403 Forbidden в API IBA Platform — проверка ключа, домена, прав доступа

Коротко: ошибка 401 — неверный или отсутствующий API-ключ. Ошибка 403 — у ключа нет нужного права. Решения разные.

Кому подходит

  • Роль: Разработчик, Интегратор
  • Уровень: Опытный

Симптом

API возвращает код 401 Unauthorized или 403 Forbidden вместо ожидаемого результата.

Какой заголовок используется

API использует заголовок X-API-Key (иногда в документации встречается написание X-API-KEY). Регистр не важен — используйте любой из них.

Исключение — 2FA-эндпоинты. Они используют не X-API-Key, а Basic Auth. Логин — API-ключ интеграции, пароль — пустой.

Диагностика и решения

Что значит

Ключ не передан, неверный, удалён или от другого сервиса.

Причины

ПричинаКак проверить
API-ключ не переданПроверьте заголовки запроса
Ключ неверныйСверьте с ключом в кабинете
Ключ удалёнПроверьте список ключей
Ключ от другого сервисаПроверьте, для какого сервиса создан

Решения

1
Проверьте заголовок X-API-Key

Он должен быть в каждом запросе. Значение — ваш ключ без кавычек.

curl --location 'https://web.multiapi.ru/api/v1/messages' \
  --header 'X-API-Key: <ваш-ключ>'
2
Проверьте ключ в кабинете

Откройте API Подключения и сверьте ключ с тем, что в вашем коде.

3
Проверьте, что ключ активен

Удалённые ключи не работают. Если ключ удалён — создайте новый.

4
Проверьте домен

Ключ от OTP не работает на Multi API. Ключ от Multi API не работает на «Мой диалог». Убедитесь, что используете ключ из нужного сервиса.

Если ключ был скомпрометирован — немедленно удалите его и создайте новый. Старый ключ может быть использован злоумышленниками.

Что приложить к обращению

Если ошибка повторяется после проверок — обратитесь в поддержку сервиса с полными данными запроса.

Контакты:

Что указать:

  • requestId из ответа — если есть.
  • Метод и URL запроса.
  • Заголовки запроса (без значения ключа — оставьте только название).
  • Время запроса.
  • Первые 4 и последние 4 символа ключа (для идентификации).

Профилактика

Следуйте этим правилам — сократите вероятность ошибок до минимума.

  1. Создавайте отдельный ключ для каждого окружения. Тест и продакшен — разные ключи.
  2. Проверяйте scope при создании ключа. Легко забыть добавить нужное право.
  3. Не удаляйте ключи без замены. Убедитесь, что новый ключ работает, прежде чем удалять старый.
  4. Храните ключи в защищённом месте. Переменные окружения, сейфы секретов. Не коммитьте в Git.
  5. Ротируйте ключи. Раз в 3–6 месяцев создавайте новые и удаляйте старые.

См. также

API-ключи

Создание и управление ключами доступа

Обработка ошибок API

Форматы ошибок для каждого API

HTTP-коды ошибок

Полный справочник кодов ответа

Multi API: ошибка 401

Частный случай для Multi API

Нужна помощь?