Skip to main content

​
Overview

mgPass supports SMS-based one-time password (OTP) verification via Hubtel. This is used for phone number verification, passwordless sign-in, and as a second factor in MFA flows.

​
How OTP Works

1

Request OTP

The application requests an OTP for a phone number. mgPass generates a 6-digit code and sends it via Hubtel SMS.
2

User receives SMS

The user receives an SMS with the code. The message includes the code and a note that it expires in 10 minutes.
3

Verify OTP

The application submits the code. mgPass verifies it against the stored code, checking expiry and attempt count.

​
Configuration

Configure the Hubtel SMS connector in the mgPass admin console:
FieldDescription
api_keyHubtel API key
client_idHubtel client ID
sender_idSMS sender name (e.g., “mgPass”)

​
OTP Parameters

ParameterValue
Code length6 digits
Expiry10 minutes
Max verification attempts3
Lockout duration15 minutes

​
Request an OTP

curl -X POST https://pass.mediageneral.digital/api/verification/sms/send \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "+233241234567"
  }'
Response: 
{
  "verification_id": "ver_abc123",
  "expires_at": 1711900600
}

​
Verify an OTP

curl -X POST https://pass.mediageneral.digital/api/verification/sms/verify \
  -H "Content-Type: application/json" \
  -d '{
    "verification_id": "ver_abc123",
    "code": "482951"
  }'
Response (success): 
{
  "verified": true,
  "phone": "+233241234567"
}
Response (failure): 
{
  "verified": false,
  "attempts_remaining": 2,
  "error": "invalid_code"
}

​
Error Handling

ErrorDescription
invalid_codeThe submitted code does not match
expiredThe OTP has expired (after 10 minutes)
max_attemptsToo many failed attempts, locked for 15 minutes
rate_limitedToo many OTP requests for this phone number
After 3 failed verification attempts, the OTP is invalidated and the phone number is locked for 15 minutes. A new OTP must be requested after the lockout expires.