API 2FA Service — обзор
API 2FA Service — Basic Auth, отдельный ключ, эндпоинты для отправки и проверки кодов
Коротко: API 2FA Service — отдельный интерфейс для подключения 2FA к вашему сайту. Отличается от OMNI API: аутентификация через Basic Auth, отдельный ключ интеграции, собственные эндпоинты.
Кому подходит
- Роль: Разработчик
- Уровень: Опытный
Что это
API 2FA Service — интерфейс для интеграции 2FA с вашим сайтом или сервисом через раздел 2FA Service. В отличие от OMNI API, этот API:
- Использует отдельный ключ интеграции — он выдаётся в разделе 2FA Service и не связан с общим API-ключом из «API Подключения».
- Аутентифицируется через Basic Auth — не через заголовок
X-API-Key. - Работает с URL интеграции — он выдаётся при настройке и может отличаться от базового URL OMNI API.
- Имеет собственные эндпоинты для отправки, проверки кода и статуса запроса.
Чем отличается от OMNI API
| Параметр | OMNI API | API 2FA Service |
|---|---|---|
| Аутентификация | Заголовок X-API-Key | Basic Auth |
| Ключ | Общий API-ключ из раздела «API Подключения» | Отдельный ключ интеграции из 2FA Service |
| URL для отправки | https://web.otpcod.ru/api/v1/messages | URL интеграции из настроек 2FA Service |
| Проверка кода | — | POST /api/v1/2fa/verify |
| Статус запроса | GET /api/v1/edrs | GET /api/v1/2fa/requests/{requestId} |
Тестовое подключение бесплатно — договор не требуется, мы предоставляем баланс для тестирования.
Перед началом
- У вас есть имя отправителя со статусом Активно.
- У вас создана 2FA-интеграция в разделе 2FA Service.
- У вас есть API-ключ интеграции и URL интеграции.
Как настроить 2FA-интеграцию →
Цикл работы
API 2FA работает в три шага:
Вы отправляете номер получателя на URL интеграции. Платформа генерирует код, отправляет его через канал и возвращает requestId.
Пользователь получает код в SMS или другом канале и вводит его на вашем сайте.
Вы отправляете requestId и code на /api/v1/2fa/verify. Платформа возвращает результат — код верный или нет.
Опционально можно:
- Получать обратные вызовы о статусах через вебхук.
- Проверять статус запроса по
requestIdв любой момент.
Методы API
API 2FA включает методы для отправки, проверки и мониторинга.
| Что нужно | Куда идти |
|---|---|
| Отправка и проверка кода — curl-примеры, параметры, ответы | Принцип работы 2FA: на стороне платформы → |
| Обратные вызовы — формат данных, статусы, обработка | Получение обратных вызовов при 2FA → |
| Проверка статуса запроса — curl-пример, поля ответа | Проверка запроса 2FA → |
Если нужна генерация на своей стороне
API 2FA Service работает только с режимом «На стороне платформы» — платформа сама генерирует и проверяет код.
Если вам нужна генерация и проверка кода на своей стороне — используйте режим Умный шлюз.
Результат
Вы понимаете, чем API 2FA отличается от OMNI API, и знаете, куда идти за деталями по каждому методу.
Частые проблемы
Причина: неверный API-ключ интеграции или неверная схема аутентификации.
Решение: проверьте, что используете Basic Auth с ключом интеграции из раздела Данные для интеграции. Не используйте заголовок X-API-Key — он не подходит для 2FA-эндпоинтов.
Причина: номер получателя недоступен или имя отправителя неактивно.
Решение: проверьте номер и статус имени отправителя.
Причина: неверный requestId или code, или истёк срок действия кода.
Решение: убедитесь, что requestId получен из ответа на отправку, а code — тот, который ввёл пользователь.
Причина: API 2FA Service работает только с генерацией на стороне платформы.
Решение: используйте режим Умный шлюз.
См. также
Нужна помощь?
- OTP-коды: support@otpcod.ru