Voice Authentication

Voice Authentication is an outbound call-to-approve primitive. Your backend asks Wave to verify someone; Wave calls that number, plays a short bilingual prompt describing what’s being authorized, captures the keypress, and returns a trustworthy, machine-readable verdict over a signed webhook (and a status API). It’s the voice equivalent of a push-to-approve / OTP step — a security factor, not a menu-tree IVR. Because the outcome gates access, it is fail-closed by design: only an explicit approval grants, and a machine/voicemail answer can never approve.

This is an outbound, API-triggered flow (Wave calls the user). It is distinct from IVR Menus (a caller dials you). Voice Authentication is gated — ask your Wave contact to enable it for your account.

Authentication & tiers

Every /v1/voice-auth endpoint needs a production API key (sk_live_) with the voice_auth:write scope (or voice_auth:read for status). Sandbox keys can’t place real authentication calls.

Create a challenge

curl https://api.wave.sa/v1/voice-auth/challenges \
  -H "Authorization: Bearer $WAVE_API_KEY" \
  -H "Idempotency-Key: 4e1a…" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+9665XXXXXXXX",
    "locale": "ar",
    "context": { "action": "login", "app_name": "Wave Secure" },
    "assurance": "standard",
    "ttl_seconds": 90,
    "retry_on_no_answer": 0,
    "metadata": { "ref": "REF-8842" }
  }'

const res = await fetch("https://api.wave.sa/v1/voice-auth/challenges", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.WAVE_API_KEY}`,
    "Idempotency-Key": "4e1a…",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    phone_number: "+9665XXXXXXXX",
    locale: "ar",
    context: {
      action: "login",
      app_name: "Wave Secure",
    },
    assurance: "standard",
    ttl_seconds: 90,
    retry_on_no_answer: 0,
    metadata: {
      ref: "REF-8842",
    },
  }),
});
console.log(await res.json());

import os

import requests

res = requests.post(
    "https://api.wave.sa/v1/voice-auth/challenges",
    headers={
        "Authorization": f"Bearer {os.environ['WAVE_API_KEY']}",
        "Idempotency-Key": "4e1a…",
    },
    json={
        "phone_number": "+9665XXXXXXXX",
        "locale": "ar",
        "context": {
            "action": "login",
            "app_name": "Wave Secure",
        },
        "assurance": "standard",
        "ttl_seconds": 90,
        "retry_on_no_answer": 0,
        "metadata": {
            "ref": "REF-8842",
        },
    },
)
print(res.json())

Field	Required	Notes
`phone_number`	✅	E.164 (`+9665…`). The number Wave dials.
`locale`	—	`ar` (default) or `en` — the prompt language.
`context`	—	`{ action, app_name, reference }`, injected into the prompt. Non-secret only — never a password/OTP/card number.
`assurance`	—	`standard` (press 1) or `number_match` (see below). Default `standard`.
`ttl_seconds`	—	30–180, default 90. The challenge expires after this.
`retry_on_no_answer`	—	0–2, default 0 — auto-redials on no-answer/busy, within the TTL.
`idempotency_key`	—	Send it as the `Idempotency-Key` header; a repeat returns the same challenge without a second call.
`metadata`	—	Opaque; echoed back in the webhook.
`brand_id`	—	An approved caller brand to speak instead of “Wave”. Omit it to use your project’s default brand, else “Wave”.

You are responsible for binding phone_number to the user you’re authenticating. Wave verifies that whoever answers that number approves — it does not verify the number belongs to the claimed identity. Look the number up from your own records for the user in session; never take it from untrusted input.

201 returns the challenge id and (for number_match) the digits to display:

{ "challenge_id": "9f1c…", "state": "initiated", "expires_at": "2026-09-01T12:01:30Z", "brand_id": null }

The verdict — fail closed

A challenge resolves to exactly one terminal state:

State	Meaning	Grants access?
`approved`	The user approved (pressed 1, or keyed the match digits)	✅ yes
`declined`	The user declined (pressed 2)	no
`timeout`	Answered, no valid input after the reprompts	no
`no_answer` / `busy` / `failed`	The call didn’t connect	no
`machine_detected`	A voicemail/machine answered	no
`expired`	No decision before `expires_at`	no

Only approved and declined are affirmative user decisions. Treat every other state as a non-grant and fail closed. Always confirm the verdict via the status API (below) before honoring an approval — defense in depth.

Answering-machine detection (AMD)

Before any prompt, Wave classifies who answered. A machine or voicemail answer resolves to machine_detected and the approval prompt is never played — so a voicemail can never capture a keypress or leave a stray approval. This is enforced, not best-effort. The classification is returned as amd_result (human or machine) on both the status API and the webhook. It errs on the safe side: an ambiguous answer is treated as a machine and blocked. As a result, a real person who gives a long spoken greeting can occasionally be misread as a machine and safely declined.

Tell your users to answer and wait for the prompt — they don’t need to say anything. A quick “hello” is fine; a drawn-out greeting is what risks a misread. Waiting for the prompt is the reliable way to be recognized as a human.

High-assurance number matching

For high-value actions (payments, admin changes), set assurance: "number_match". The 201 response includes match_digits (e.g. "47") — display them to your user. The call then asks the callee to key those exact digits to approve. There is no “press 1” shortcut in this mode, and a wrong or partial entry resolves to timeout (a non-grant) — so it defeats “just press 1” MFA-fatigue and accidental approvals, and the short code can’t be guessed (a wrong entry ends the attempt).

{ "challenge_id": "9f1c…", "state": "initiated", "expires_at": "…", "match_digits": "47" }

Caller brand

By default the call says “This is Wave calling…”. Your organization can make it say your own name (a caller brand) instead, in the call language: “This is Acme calling to verify a login on Acme App…”. A caller brand is a spoken name only — the caller ID stays Wave’s verified number. Get a brand approved (portal). In the developer portal, open Caller brands and request a brand with an English name and an Arabic name. It needs two approvals before a call can use it: an owner or admin of your organization (a request by an owner or admin skips this step), then Wave. Names are 2–40 characters (letters, digits, spaces and . & ' -; no web addresses; no run of 4 or more digits); the Arabic name must use Arabic letters. A brand’s names never change — to use a new name, request a new brand. Use it on a challenge. Pass brand_id on create. The call speaks:

the brand_id you send, if any; else
your project’s default brand (set on the Caller brands page); else
“Wave” — so an integration that never sends brand_id keeps working.

A brand_id must be an approved brand of your organization; anything else (unknown, pending, rejected, retired, another organization’s) returns 422 VOICE_AUTH_BRAND_NOT_APPROVED and no call is placed. The challenge keeps the name it started with, so a brand retired mid-call never changes what the user hears. The 201, the status API and the webhook carry brand_id (null = “Wave”). List your brands from your backend.

curl https://api.wave.sa/v1/voice-auth/brands?limit=20 \
  -H "Authorization: Bearer $WAVE_API_KEY"

const res = await fetch("https://api.wave.sa/v1/voice-auth/brands?limit=20", {
  headers: {
    Authorization: `Bearer ${process.env.WAVE_API_KEY}`,
  },
});
console.log(await res.json());

import os

import requests

res = requests.get(
    "https://api.wave.sa/v1/voice-auth/brands?limit=20",
    headers={
        "Authorization": f"Bearer {os.environ['WAVE_API_KEY']}",
    },
)
print(res.json())

{
  "data": [
    {
      "brand_id": "7b0e…",
      "name_en": "Acme",
      "name_ar": "أكمي",
      "status": "approved",
      "rejection_reason": null,
      "is_default": true,
      "created_at": "2026-10-01T09:12:00Z",
      "decided_at": "2026-10-01T11:40:00Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Needs a production key with voice_auth:read. Returns every brand of your organization with its status (pending_tenant, pending_wave, approved, rejected, retired), the reject reason, and is_default for the key’s project. Paginate with cursor = the previous next_cursor.

If Wave’s text-to-speech is unavailable, Wave can fall back to pre-recorded prompts. In that mode the standard prompt does not name a caller (neither “Wave” nor your brand); the number-match prompt still says your brand. brand_id is still stored and returned.

The result webhook

On a terminal state Wave sends a signed voice_auth.completed event to your project’s webhook endpoint:

{
  "event": "voice_auth.completed",
  "data": {
    "challenge_id": "9f1c…",
    "state": "approved",
    "decided_at": "2026-09-01T12:00:41Z",
    "attempts": 1,
    "amd_result": "human",
    "brand_id": null
  }
}

Verify every delivery:

X-Wave-Signature — sha256=…, an HMAC-SHA256 of the raw body with your endpoint’s signing secret. Reject a mismatch.
X-Wave-Timestamp — unix seconds; reject deliveries older than your window (e.g. 5 minutes).
X-Wave-Event-Id — stable across retries; dedupe on it.

The webhook is a notification — reconfirm via the status API before granting.

Poll status

curl https://api.wave.sa/v1/voice-auth/challenges/9f1c… \
  -H "Authorization: Bearer $WAVE_API_KEY"

const res = await fetch("https://api.wave.sa/v1/voice-auth/challenges/9f1c…", {
  headers: {
    Authorization: `Bearer ${process.env.WAVE_API_KEY}`,
  },
});
console.log(await res.json());

import os

import requests

res = requests.get(
    "https://api.wave.sa/v1/voice-auth/challenges/9f1c…",
    headers={
        "Authorization": f"Bearer {os.environ['WAVE_API_KEY']}",
    },
)
print(res.json())

Returns the current state, attempts, amd_result, brand_id, timestamps, and (once terminal) the decision. Scoped to your organization only.

Testing each verdict

There is no sandbox simulation for Voice-Auth — testing needs a production key and a real phone you control. Each terminal state is reproducible by how you answer the call:

To get	Answer the call, then…
`approved`	standard: press 1. number_match: key the exact `match_digits` shown.
`declined`	press 2 (standard only).
`timeout`	press nothing and stay on the line — resolves after the reprompts. For `number_match`, keying the wrong or a partial code lands here too.
`machine_detected`	let the call reach voicemail, or answer with a long/machine-like spoken greeting — the prompt is never played.

Confirm each on the status API (state, amd_result, attempts). Space out repeated tests to the same number, or you’ll hit VOICE_AUTH_RATE_LIMITED.

Idempotency, rate limits & abuse controls

Idempotency — send an Idempotency-Key; a retry with the same key returns the same challenge and never places a second call.
Per-number & per-originator limits — Wave caps challenges to a single number and per API key, and blocks known-abusive numbers/prefixes, to prevent voice-bombing and toll fraud. Over a limit → 429.

Errors

Code	HTTP	When
`VOICE_AUTH_DISABLED`	503	Not enabled for this account
`SANDBOX_KEY_NOT_ALLOWED`	400	A sandbox key was used
`VALIDATION_ERROR`	400	Bad phone/locale/ttl, or a secret-bearing `context`
`VOICE_AUTH_BLOCKED`	403	The target number is blocklisted
`VOICE_AUTH_RATE_LIMITED`	429	A per-number/per-originator limit was hit
`VOICE_AUTH_NOT_FOUND`	404	No such challenge for your organization
`VOICE_AUTH_BRAND_NOT_APPROVED`	422	`brand_id` is not an approved caller brand of your organization

Get Started

Voice

Web Callback

WhatsApp

Reference

Voice Authentication

Authentication & tiers

Create a challenge

The verdict — fail closed

Answering-machine detection (AMD)

High-assurance number matching

Caller brand

The result webhook

Poll status

Testing each verdict

Idempotency, rate limits & abuse controls

Errors

​Authentication & tiers

​Create a challenge

​The verdict — fail closed

​Answering-machine detection (AMD)

​High-assurance number matching

​Caller brand

​The result webhook

​Poll status

​Testing each verdict

​Idempotency, rate limits & abuse controls

​Errors

Authentication & tiers

Create a challenge

The verdict — fail closed

Answering-machine detection (AMD)

High-assurance number matching

Caller brand

The result webhook

Poll status

Testing each verdict

Idempotency, rate limits & abuse controls

Errors