Интеграция с приложением
Зарегистрируйте приложение и выполняйте вход пользователей через размещённую страницу OpenID Connect или вызывайте подписанный серверный API.
Ваше приложение подключается к Yeap Verify одним из двух способов:
| Способ | Подходит для |
|---|---|
| Размещённая страница входа (OpenID Connect) | Приложений, которые уже поддерживают OpenID Connect. Verify показывает число и ждёт подтверждения; ваше приложение получает ID-токен |
| Серверный API | Приложений, в которые вы сами добавляете второй шаг: push, TOTP или резервные коды |
Для обоих способов нужно приложение, зарегистрированное в панели команды.
Регистрация приложения
- В панели команды откройте Yeap Verify → Приложения и нажмите Добавить приложение.
- Введите Имя. Пользователи видят его в Yeap Verify, когда подтверждают вход.
- Для размещённой страницы добавьте URI перенаправления, по одному на строку. При желании добавьте URL вебхука (HTTPS) для получения результатов.
- Нажмите Сохранить. Client ID и Client secret показываются один раз. Храните секрет только на своём сервере.


Новый секрет заменяет секрет; старый сразу перестаёт работать.
В Yeap Verify → Политики у каждого приложения есть две настройки:
| Настройка | Значение |
|---|---|
| Если Verify недоступен | Блокировать (по умолчанию) или Разрешить входы, когда ваше приложение не может связаться с Verify. Применяет её ваше приложение; проверка состояния серверного API возвращает это значение |
| Число цифр | Сколько цифр вводит пользователь: от 3 до 6. Для важных приложений используйте больше |
Размещённая страница входа (OpenID Connect)
Страница входа вашей команды — https://<team>.verify.yeap.cloud, она же является издателем (issuer). Конфигурация находится по адресу https://<team>.verify.yeap.cloud/.well-known/openid-configuration.
| Поток | Authorization code с PKCE (S256). scope должен включать openid; state обязателен |
| Аутентификация клиента | client_secret_basic или client_secret_post |
| ID-токен | Подписан ES256. Утверждения включают sub (ID пользователя Verify), preferred_username, amr и tx_id |
| Какой пользователь | Передайте login_hint_token — короткоживущий JWT, который подписывает ваш сервер (см. ниже). Простой login_hint не принимается |
Пользователь уже ввёл пароль в вашем приложении, поэтому вы знаете, кто он. Ваш сервер создаёт login_hint_token как JWT HS256, подписанный client secret:
{ "iss": "<client ID>", "aud": "https://acme.verify.yeap.cloud", "sub": "alice", "exp": <now + up to 300 seconds> }Затем перенаправьте браузер на https://acme.verify.yeap.cloud/oauth/v1/authorize с параметрами response_type=code, client_id, redirect_uri, scope=openid, state, nonce, code_challenge, code_challenge_method=S256 и login_hint_token. Страница показывает число и, как только пользователь подтвердит вход на телефоне, перенаправляет обратно в ваше приложение с кодом. Обменяйте код на токен в конечной точке token, указанной в конфигурации.
Серверный API
Базовый URL: https://verify.yeap.cloud. Каждый запрос подписывается client secret приложения.
| Заголовок | Значение |
|---|---|
Yeap-Client-Id | Client ID приложения |
Yeap-Timestamp | Текущее время Unix в секундах. Должно отличаться от часов сервера не более чем на 5 минут |
Yeap-Nonce | От 16 до 64 случайных символов из A–Z a–z 0–9 _ -, новый для каждого запроса |
Yeap-Signature | HMAC-SHA256 в hex с client secret по шести строкам ниже |
Подписываемый текст — это следующие строки, соединённые через \n: yeap-verify-hmac-v1, метод, путь со строкой запроса, метка времени, nonce и SHA-256 в hex от тела запроса (для GET — от пустого тела).
Конечные точки
| Запрос | Ответ |
|---|---|
GET /api/v1/health | {"status":"ok","fail_mode":"closed"}. Вызывайте перед началом входа |
POST /api/v1/auth | Запускает проверку. Тело: user, factor (push, totp или backup, по умолчанию push), необязательные ip и app (показываются на телефоне), passcode для TOTP и резервных кодов |
GET /api/v1/auth/{tx_id} | {"tx_id":…,"status":…} |
status сначала равен pending, затем одному из allow, deny, timeout или fraud (пользователь нажал Это был не я). Для push ответ также содержит number, который нужно показать пользователю, и expires_at. Опрашивайте каждые 1–2 секунды или используйте вебхук. Для totp и backup ответ сразу окончательный.
Пример (Python)
import hashlib, hmac, json, secrets, time
import requests
BASE = "https://verify.yeap.cloud"
CLIENT_ID = "ci_..."
SECRET = "cs_..."
def call(method, path, body=None):
data = json.dumps(body).encode() if body is not None else b""
ts, nonce = str(int(time.time())), secrets.token_urlsafe(24)
text = "\n".join(["yeap-verify-hmac-v1", method, path, ts, nonce, hashlib.sha256(data).hexdigest()])
headers = {
"Yeap-Client-Id": CLIENT_ID, "Yeap-Timestamp": ts, "Yeap-Nonce": nonce,
"Yeap-Signature": hmac.new(SECRET.encode(), text.encode(), hashlib.sha256).hexdigest(),
}
if body is not None:
headers["Content-Type"] = "application/json"
return requests.request(method, BASE + path, data=data, headers=headers, timeout=10).json()
tx = call("POST", "/api/v1/auth", {"user": "alice", "factor": "push", "ip": "203.0.113.7", "app": "Intranet portal"})
print("Enter this number in Yeap Verify:", tx["number"])
while (r := call("GET", "/api/v1/auth/" + tx["tx_id"]))["status"] == "pending":
time.sleep(1.5)
print(r["status"]) # allow, deny, timeout or fraudОшибки
| HTTP | error | Значение |
|---|---|---|
| 401 | unauthorized, timestamp_out_of_window, replayed_request | Неверная подпись или Client ID, часы расходятся более чем на 5 минут, или nonce использован повторно |
| 404 | user_not_found | Нет пользователя Verify с таким именем |
| 429 | rate_limited | Слишком много запросов для этого пользователя. Повторите попытку чуть позже |
| 503 | org_suspended и другие, с "status":"unavailable" | Verify не может ответить, например, истёк тариф. Примените свою настройку Если Verify недоступен |
Вебхук
Если у приложения указан URL вебхука, Verify отправляет каждый окончательный результат запросом POST с JSON-телом {"event":"auth.result","tx_id":…,"status":…,"reason":…,"at":…}. Он подписывается так же, с заголовками X-Yeap-Client-Id, X-Yeap-Timestamp, X-Yeap-Nonce и X-Yeap-Signature, по пути вашего URL вебхука. Проверяйте подпись, прежде чем доверять запросу.