Что такое API-ключ
API-ключ — это зашифрованный код, по которому МТС Exolve идентифицирует приложение и разрешает работать с услугами и ресурсами платформы.
С помощью ключа внешняя система может обращаться к ресурсам и услугам приложения: отправлять сообщения, совершать вызовы, получать статистику коммуникаций и многое другое.
Ключ создаётся на уровне приложения. Поэтому API-запрос получает доступ только к тем номерам, услугам и настройкам, которые относятся к этому приложению.
Как получить API-ключ
Для каждого приложения автоматически формируется свой уникальный ключ. Чтобы получить его:
- Войдите в Личный кабинет МТС Exolve
- Перейдите в раздел «Ключи» → «API-ключи» нужного приложения
- Скопируйте ключ
При необходимости вы можете выпустить дополнительные ключи. Несколько ключей нужны, чтобы:
- Разные интеграции не использовали общий ключ. Это позволяет понимать, какая система использует конкретный ключ, и отключить скомпроментированный ключ, не останавливая остальные интеграции
- Ротировать ключи без простоя: новый ключ → переключили сервис → старый ключ отозвали
Кликните на кнопку «Создать ключ» — до 20 ключей на одно приложение. Для каждого ключа можно задать внутреннее название, чтобы быстрее найти нужный в списке ключей.
Как удалить API-ключ
Чтобы удалить ключ, выберите его чекбоксом и кликните на кнопку «Удалить» над таблицей. После удаления ключ немедленно станет недействительным: использовать его для управления услугами и ресурсами этого приложения уже не получится.
Перед удалением убедитесь, что этот ключ больше не используется в ваших системах и интеграциях.
Как перевыпустить API-ключ
Чтобы пересоздать ключ, кликните на иконку перевыпуска напротив нужного ключа.
После перевыпуска старый ключ сразу перестанет работать. Замените его на новый в вашей системе, чтобы продолжить работать с услугами.
Заранее запланируйте замену ключа в интеграции, чтобы избежать остановки сервиса.
Как использовать ключ в API-запросе
Ключ нужно передавать в HTTP-заголовке Authorization в каждом запросе к API МТС Exolve. Например, в Postman это выглядит так:
Интеграция настроена корректно, если API:
- принимает запрос без ошибок аутентификации
- возвращает успешный HTTP-статус
- выполняет запрошенную операцию
- возвращает ответ или идентификатор созданной сущности (если предусмотрено)
Возможные ошибки
| Код ошибки | Причина | Как исправить |
|---|---|---|
| 400 Bad Request | Запрос содержит некорректные или недостающие параметры | Сверьте тело запроса, типы данных и обязательные параметры с документацией метода |
| 401 Unauthorized | API-ключ отсутствует или передан некорректно | Проверьте: указан Bearer в типе авторизации полностью ли скопирован ключ не содержит ли значение лишних пробелов или кавычек |
| 403 Forbidden | Аккаунт неактивен, заблокирован или не имеет доступа к операции | Проверьте статус аккаунта и доступность услуги. |
| 404 Not Found | Неверно указан адрес API либо запрашиваемый ресурс не найден | Проверьте URL метода и убедитесь, что используемый номер или другой ресурс относится к выбранному приложению. |
Как безопасно использовать API-ключ
API-ключ выполняет функцию пароля. Если он попадёт к третьим лицам, они могут получить доступ к услугам и ресурсам вашего приложения и подвергнуть аккаунт риску.
Рекомендуем:
- Хранить ключи в защищённом хранилище секретов. Не сохраняйте ключ в коде, репозиториях, Confluence или логах
- Предоставлять доступ к ключам только тем сервисам и сотрудникам, которым вы доверяете
- Перевыпускать ключи каждые 1-3 месяца или сразу после увольнения сотрудника, изменения интеграции либо при подозрении на утечку
- Использовать несколько ключей для разных задач. Так проще определить источник проблемы и быстрее отключить только скомпроментированный ключ
- Удалять ключи, если они больше не используются
