OTP Verification Guide - How to Validate One-Time Passwords Securely
Endpoint
POST https://otp.api.engagelab.cc/v1/verifications
Autenticación
Se adopta el método HTTP Basic Authentication. Añadir Authorization en el encabezado HTTP:
Authorization: Basic ${base64_auth_string}
Authorization: Basic ${base64_auth_string}
Este bloque de código se muestra en una ventana flotante
El algoritmo de generación del valor anterior base64_auth_string es: base64(dev_key:dev_secret)
Ejemplo de solicitud
Encabezado de solicitud
POST /v1/verifications HTTP/1.1
Content-Type: application/json
Authorization: Basic amlndWFuZ2RldjpkZXZfc2VjcmV0
POST /v1/verifications HTTP/1.1
Content-Type: application/json
Authorization: Basic amlndWFuZ2RldjpkZXZfc2VjcmV0
Este bloque de código se muestra en una ventana flotante
Cuerpo de la solicitud
{
"message_id": "1725407449772531712",
"verify_code": "667090"
}
{
"message_id": "1725407449772531712",
"verify_code": "667090"
}
Este bloque de código se muestra en una ventana flotante
Parámetros de la solicitud
| Parámetro | Tipo | Obligatoriedad | Descripción |
|---|---|---|---|
| message_id | String | Obligatorio | ID del mensaje asociado al código de verificación, devuelto por el endpoint /messages |
| verify_code | String | Obligatorio | Código de verificación que se va a validar |
Parámetros de la respuesta
Respuesta correcta
| Campo | Tipo | Obligatoriedad | Descripción |
|---|---|---|---|
| message_id | String | Obligatorio | ID del mensaje asociado al código de verificación, devuelto por el endpoint /v1/messages |
| verify_code | String | Obligatorio | Código de verificación que se va a validar |
| verified | Boolean | Obligatorio | Resultado de la verificación; true para una validación correcta, false para un fallo |
{
"message_id": "1725407449772531712",
"verify_code": "667090",
"verified": true
}
{
"message_id": "1725407449772531712",
"verify_code": "667090",
"verified": true
}
Este bloque de código se muestra en una ventana flotante
Se debe tener en cuenta que, para el código de verificación del mismo mensaje, si la solicitud de validación se realiza correctamente, cualquier solicitud de validación posterior fallará, lo que indica que la verificación de este mensaje ya se ha completado; los códigos de verificación validados correctamente no se pueden volver a validar.
Respuesta de error
Código de estado HTTP 4xx o 5xx; el cuerpo de la respuesta incluye los siguientes campos:
| Campo | Tipo | Obligatoriedad | Descripción |
|---|---|---|---|
| code | int | Obligatorio | Código de error; consulte Códigos de error para obtener más detalles |
| message | String | Obligatorio | Detalles del error |
{
"code": 3003,
"message": "verify code has expired"
}
{
"code": 3003,
"message": "verify code has expired"
}
Este bloque de código se muestra en una ventana flotante
Códigos de error
| Código de error | Código HTTP | Descripción |
|---|---|---|
| 1000 | 500 | Error interno |
| 2001 | 401 | Fallo de autenticación; token incorrecto o ausente |
| 2002 | 401 | Fallo de autenticación; el token ha caducado o se ha deshabilitado |
| 2004 | 403 | Sin permisos para llamar a esta API |
| 3001 | 400 | Formato de parámetro de solicitud no válido; verificar que coincide con el formato JSON requerido |
| 3002 | 400 | Parámetros de solicitud incorrectos; verificar que cumplen los requisitos |
| 3003 | 400 | Código de verificación caducado o ya verificado; para este código de error, se debe enviar un nuevo mensaje de verificación |
| 4001 | 400 | El mensaje no existe |
