Authevo documentation

Introduction

Authevo is a WhatsApp OTP + TOTP verification API for Egypt and the wider MENA region. Send a one-time code to a phone number over WhatsApp and verify what your user typed back, or enroll a phone for TOTP two-factor and verify codes from any authenticator app — two independent methods, one account.

Every request is a plain HTTPS call against a single base URL. Responses come back as JSON, wrapped in a predictable envelope, so the same two calls work in any language your backend already speaks.

The two-call model

POST /v1/otp/send

Send a one-time code to a phone number.

POST /v1/otp/verify

Check the code the user entered.

Codes are delivered over WhatsApp, with Telegram as a fallback if WhatsApp can't be reached. Link each recipient's Telegram once — a one-tap step, ideally right after they sign up — and every fallback after that is automatic; your integration code never changes.

Quickstart

Integrate the two-call flow in a couple of minutes. WhatsApp sending activates once your Meta Business Verification clears; link Telegram once per recipient (see below) and it covers you in the meantime.

# 1. Send a one-time code over WhatsApp
curl -X POST https://api.authevo.dev/v1/otp/send \
  -H "Authorization: Bearer sk_…" \
  -H "Content-Type: application/json" \
  -d '{ "phone": "+201234567890" }'

# 2. Verify the code your user entered
curl -X POST https://api.authevo.dev/v1/otp/verify \
  -H "Authorization: Bearer sk_…" \
  -H "Content-Type: application/json" \
  -d '{ "phone": "+201234567890", "code": "123456" }'

Authentication

Authevo uses bearer authentication. Pass your secret key in the Authorization header on every request.

Authorization: Bearer sk_…

There are no other auth schemes — no OAuth, no sessions, no logins. A valid secret key is all a request needs.

Two-Factor (TOTP)

A second, independent verification method — any authenticator app (Google Authenticator, Authy, 1Password), no message ever sent, just $0.002 per verification. Enroll once, then verify a rotating 6-digit code forever after.

curl -X POST https://api.authevo.dev/v1/totp/enroll \
  -H "Authorization: Bearer sk_…" \
  -H "Content-Type: application/json" \
  -d '{ "phone": "+201234567890" }'

{
  "data": {
    "secret": "JBSWY3DPEHPK3PXP",
    "otpauth_url": "otpauth://totp/Authevo:+201234567890?secret=JBSWY3DPEHPK3PXP&issuer=Authevo&algorithm=SHA1&digits=6&period=30",
    "qr_code": "data:image/png;base64,iVBORw0KGgo...",
    "already_enrolled": false
  }
}

curl -X POST https://api.authevo.dev/v1/totp/verify \
  -H "Authorization: Bearer sk_…" \
  -H "Content-Type: application/json" \
  -d '{ "phone": "+201234567890", "code": "123456" }'

{
  "data": {
    "verified": true,
    "first_confirm": true
  }
}

curl -X POST https://api.authevo.dev/v1/totp/disable \
  -H "Authorization: Bearer sk_…" \
  -H "Content-Type: application/json" \
  -d '{ "phone": "+201234567890" }'

{
  "data": {
    "disabled": true
  }
}

Errors

Authevo uses standard HTTP status codes. Successful responses are wrapped in a data object; failures return an error object with a machine-readable code and a human-readable message.

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "body/phone must match pattern \"^\\+[1-9]\\d{6,14}$\""
  }
}

Rate limits

Requests are rate limited per account. When you exceed the limit, the API responds with 429 RATE_LIMIT_EXCEEDED — back off and retry after a short delay.