Integra tu aplicación
Registra una aplicación, inicia la sesión de los usuarios mediante la página alojada de OpenID Connect o llama a la API de servidor firmada.
Tu aplicación se conecta a Yeap Verify de una de estas dos formas:
| Forma | Ideal para |
|---|---|
| Página de inicio de sesión alojada (OpenID Connect) | Aplicaciones que ya admiten OpenID Connect. Verify muestra el número y espera la aprobación; tu aplicación recibe un ID token |
| API de servidor | Aplicaciones en las que tú mismo añades el segundo paso: push, TOTP o códigos de respaldo |
Ambas necesitan una aplicación registrada en el panel del equipo.
Registra una aplicación
- En el panel del equipo, abre Yeap Verify → Aplicaciones y haz clic en Añadir aplicación.
- Introduce un Nombre. Los usuarios lo ven en Yeap Verify cuando aprueban un inicio de sesión.
- Para la página alojada, añade tus URI de redirección, una por línea. Opcionalmente, añade una URL del webhook (HTTPS) para recibir los resultados.
- Haz clic en Guardar. El Client ID y el Client secret se muestran una sola vez. Guarda el secreto solo en tu servidor.


Nuevo secreto sustituye el secreto; el anterior deja de funcionar al instante.
En Yeap Verify → Políticas, cada aplicación tiene dos ajustes:
| Ajuste | Significado |
|---|---|
| Si Verify no responde | Bloquear (por defecto) o Permitir los inicios de sesión cuando tu aplicación no puede llegar a Verify. Lo aplica tu aplicación; la comprobación de estado de la API de servidor lo devuelve |
| Dígitos del número | Cuántos dígitos introduce el usuario: de 3 a 6. Usa más para aplicaciones sensibles |
Página de inicio de sesión alojada (OpenID Connect)
La página de inicio de sesión de tu equipo es https://<team>.verify.yeap.cloud, que también es el emisor (issuer). La configuración está en https://<team>.verify.yeap.cloud/.well-known/openid-configuration.
| Flujo | Código de autorización con PKCE (S256). scope debe incluir openid; state es obligatorio |
| Autenticación del cliente | client_secret_basic o client_secret_post |
| ID token | Firmado con ES256. Las claims incluyen sub (el ID de usuario de Verify), preferred_username, amr y tx_id |
| Qué usuario | Pasa login_hint_token, un JWT de corta duración que firma tu servidor (ver abajo). No se acepta un login_hint simple |
El usuario ya ha introducido su contraseña en tu aplicación, así que sabes quién es. Tu servidor crea el login_hint_token como un JWT HS256 firmado con el client secret:
{ "iss": "<client ID>", "aud": "https://acme.verify.yeap.cloud", "sub": "alice", "exp": <now + up to 300 seconds> }Después redirige el navegador a https://acme.verify.yeap.cloud/oauth/v1/authorize con response_type=code, client_id, redirect_uri, scope=openid, state, nonce, code_challenge, code_challenge_method=S256 y login_hint_token. La página muestra el número y redirige de vuelta a tu aplicación con un código cuando el usuario aprueba en el teléfono. Intercambia el código en el endpoint de token que figura en la configuración.
API de servidor
URL base: https://verify.yeap.cloud. Cada solicitud se firma con el client secret de la aplicación.
| Cabecera | Valor |
|---|---|
Yeap-Client-Id | El client ID de la aplicación |
Yeap-Timestamp | Hora Unix actual en segundos. Debe estar a menos de 5 minutos del reloj del servidor |
Yeap-Nonce | De 16 a 64 caracteres aleatorios de A–Z a–z 0–9 _ -, nuevo en cada solicitud |
Yeap-Signature | HMAC-SHA256 en hexadecimal con el client secret sobre las seis líneas siguientes |
El texto firmado son estas líneas unidas con \n: yeap-verify-hmac-v1, el método, la ruta con la cadena de consulta, la marca de tiempo, el nonce y el SHA-256 en hexadecimal del cuerpo de la solicitud (de un cuerpo vacío en GET).
Endpoints
| Solicitud | Respuesta |
|---|---|
GET /api/v1/health | {"status":"ok","fail_mode":"closed"}. Llámalo antes de iniciar un inicio de sesión |
POST /api/v1/auth | Inicia una comprobación. Cuerpo: user, factor (push, totp o backup, por defecto push), ip y app opcionales (se muestran en el teléfono), passcode para TOTP y códigos de respaldo |
GET /api/v1/auth/{tx_id} | {"tx_id":…,"status":…} |
status es pending y luego uno de allow, deny, timeout o fraud (el usuario pulsó No fui yo). Para push, la respuesta también incluye el number que se muestra al usuario y expires_at. Consulta cada 1 o 2 segundos, o usa el webhook. Para totp y backup la respuesta es definitiva al instante.
Ejemplo (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 fraudErrores
| HTTP | error | Significado |
|---|---|---|
| 401 | unauthorized, timestamp_out_of_window, replayed_request | Firma o client ID incorrectos, reloj desviado más de 5 minutos o un nonce reutilizado |
| 404 | user_not_found | No hay ningún usuario de Verify con ese nombre |
| 429 | rate_limited | Demasiadas solicitudes para este usuario. Inténtalo de nuevo en breve |
| 503 | org_suspended y otros, con "status":"unavailable" | Verify no puede responder, por ejemplo porque el plan venció. Aplica tu ajuste Si Verify no responde |
Webhook
Si la aplicación tiene una URL del webhook, Verify envía cada resultado final como un POST con el cuerpo JSON {"event":"auth.result","tx_id":…,"status":…,"reason":…,"at":…}. Se firma de la misma forma, con las cabeceras X-Yeap-Client-Id, X-Yeap-Timestamp, X-Yeap-Nonce y X-Yeap-Signature, sobre la ruta de la URL de tu webhook. Comprueba la firma antes de confiar en él.