OTP Verification Guide - How to Validate One-Time Passwords Securely
Endpoint
POST https://otp.api.engagelab.cc/v1/verifications
Authentifizierung
Die Authentifizierung erfolgt über HTTP Basic Authentication. Fügen Sie dazu im HTTP-Header Folgendes hinzu:
Authorization: Basic ${base64_auth_string}
Authorization: Basic ${base64_auth_string}
Diesen Codeblock im schwebenden Fenster anzeigen
Der base64_auth_string wird wie folgt generiert: base64(dev_key:dev_secret)
Beispiel für eine Anfrage
Anfrage-Header
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
Diesen Codeblock im schwebenden Fenster anzeigen
Anfrage-Body
{
"message_id": "1725407449772531712",
"verify_code": "667090"
}
{
"message_id": "1725407449772531712",
"verify_code": "667090"
}
Diesen Codeblock im schwebenden Fenster anzeigen
Anfrageparameter
| Parameter | Typ | Erforderlich | Beschreibung |
|---|---|---|---|
| message_id | String | Erforderlich | Die Nachrichten-ID, die dem Verifizierungscode zugeordnet ist. Wird vom /messages-Endpunkt zurückgegeben. |
| verify_code | String | Erforderlich | Der zu validierende Verifizierungscode. |
Antwortparameter
Erfolgreiche Antwort
| Feld | Typ | Erforderlich | Beschreibung |
|---|---|---|---|
| message_id | String | Erforderlich | Die Nachrichten-ID, die dem Verifizierungscode zugeordnet ist. Wird vom /v1/messages-Endpunkt zurückgegeben. |
| verify_code | String | Erforderlich | Der zu validierende Verifizierungscode. |
| verified | Boolean | Erforderlich | Ergebnis der Verifizierung: true bei erfolgreicher Validierung, false bei Fehlschlag. |
{
"message_id": "1725407449772531712",
"verify_code": "667090",
"verified": true
}
{
"message_id": "1725407449772531712",
"verify_code": "667090",
"verified": true
}
Diesen Codeblock im schwebenden Fenster anzeigen
Beachte: Für denselben Verifizierungscode einer Nachricht schlägt jeder weitere Validierungsversuch nach einem erfolgreichen Durchlauf fehl. Das bedeutet, dass die Verifizierung für diese Nachricht bereits abgeschlossen wurde; ein erfolgreich verifizierter Code kann nicht erneut validiert werden.
Fehlerantwort
Bei einem Fehler wird ein HTTP-Statuscode 4xx oder 5xx zurückgegeben. Der Antwort-Body enthält folgende Felder:
| Feld | Typ | Erforderlich | Beschreibung |
|---|---|---|---|
| code | int | Erforderlich | Fehlercode, siehe Fehlercodes für Details |
| message | String | Erforderlich | Fehlerdetails |
{
"code": 3003,
"message": "verify code has expired"
}
{
"code": 3003,
"message": "verify code has expired"
}
Diesen Codeblock im schwebenden Fenster anzeigen
Fehlercodes
| Fehlercode | HTTP-Code | Beschreibung |
|---|---|---|
| 1000 | 500 | Interner Fehler |
| 2001 | 401 | Authentifizierung fehlgeschlagen, Token fehlt oder ist falsch |
| 2002 | 401 | Authentifizierung fehlgeschlagen, Token abgelaufen oder deaktiviert |
| 2004 | 403 | Keine Berechtigung, diese API aufzurufen |
| 3001 | 400 | Ungültiges Anfrageparameter-Format, bitte stellen Sie sicher, dass das JSON-Format korrekt ist |
| 3002 | 400 | Fehlerhafte Anfrageparameter, bitte prüfen Sie die Anforderungen |
| 3003 | 400 | Verifizierungscode abgelaufen oder bereits verifiziert, für diesen Fehlercode muss eine neue Verifizierungsnachricht gesendet werden |
| 4001 | 400 | Die Nachricht existiert nicht |
