Verify API

One-time-password (OTP) issuance and validation across SMS, voice (TTS), email, and WhatsApp. Two patterns:

Direct — issue an OTP to a phone / email; validate the code the user enters.
Profile-based — define a verify profile (channel, code length, expiration, locale, sender), then reference it by name from your app. Lets you tune behavior without redeploying.

Base path: /api/v1/verify Authentication: API key (X-API-Key) or session JWT.

Languages

The mirror-every-call pattern below — one <Tabs> strip, curl plus one tab per typed SDK — recurs on every worked sample on this page, so the languages stay parallel as the page evolves. The core resources on this page have typed helpers in the SDKs, so each language calls into verify.send / verify.check (Python), Verify().Send / Verify().Check (Go), and verify.send / verify.check (Node) — only reach for the generic request()/Request() escape hatch on a page whose endpoint has no helper yet.

curl
Node.js
Python
Go

curl -X POST https://api.orbit.devotel.io/api/v1/verify/send \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "to": "+14155552671", "channel": "sms" }'

import { Orbit } from "@devotel-orbit/node";

const orbit = new Orbit({ apiKey: process.env.ORBIT_API_KEY });

const sent = await orbit.verify.send("+14155552671", "sms");
console.log(sent.data.id); // vrf_… — hand back into check below

const checked = await orbit.verify.check({
  verification_id: sent.data.id,
  code: "123456",
});
console.log(checked.data.valid);

See the Node SDK for install and configuration.

from orbit_sdk import OrbitClient

client = OrbitClient.from_env()  # reads ORBIT_API_KEY

sent = client.verify.send(to="+14155552671", channel="sms")
print(sent["data"]["id"])  # vrf_… — hand back into check below

checked = client.verify.check(
    verification_id=sent["data"]["id"],
    code="123456",
)
print(checked["data"]["valid"])

See the Python SDK for install and configuration.

client, err := orbit.NewClient(os.Getenv("ORBIT_API_KEY"))
if err != nil {
    log.Fatal(err)
}
ctx := context.Background()

sent, err := client.Verify().Send(ctx, "+14155552671", "sms")
if err != nil {
    log.Fatal(err)
}
fmt.Println(sent.Data.ID) // vrf_… — hand back into Check below

checked, err := client.Verify().Check(ctx, sent.Data.ID, "123456")
if err != nil {
    log.Fatal(err)
}
fmt.Println(checked.Data.Valid)

The Go SDK wraps verify (along with messaging, lookup, webhook-verification) — vendor it with go get github.com/devotel/orbit-go/orbit.

The same shape works for the rest of this page — verify.check folds in wherever a worked call happens. Raw curl in the body of this page works identically. Full SDK index at SDK quickstart.

Send & check

Method	Path	Purpose
`POST`	`/api/v1/verify/send`	Issue an OTP
`POST`	`/api/v1/verify/bulk`	Issue OTPs to up to 1000 recipients in one call (details)
`POST`	`/api/v1/verify/check`	Validate an OTP code

Bulk send

POST /api/v1/verify/bulk fans an OTP out to up to 1000 recipients that share one channel and (optionally) one verify profile_id / template_variables bag — built for login surges and password-reset campaigns. Each recipient flows through the same per-recipient pipeline as POST /verify/send (E.164 / email validation, per-recipient rate limit, fraud velocity, wallet deduct, MessageRouter dispatch), so no new outbound path is introduced. Recipients are de-duplicated (first-occurrence order preserved) and dispatched with a bounded-parallel worker pool; one recipient’s failure never aborts the batch. This endpoint is rate-limited to 2 requests / minute per tenant (each call can mint up to 1000 OTPs) — operators can raise it with a per-org override. Request body

Field	Type	Default	Notes
`recipients`	`string[]`	—	Required. 1–1000 destinations (E.164 phone or email, per `channel`).
`channel`	string	`sms`	Shared channel: `sms`, `whatsapp`, `email`, `voice`, `viber`, `telegram`, `silent`, `sna`, `magic_link`.
`country`	string	—	ISO 3166-1 alpha-2 hint applied to every recipient (national → E.164).
`code_length`	integer	6	Digits per code (4–8).
`max_attempts`	integer	3	Max check attempts per code (1–10).
`profile_id`	string	—	Verify profile applied uniformly to the batch.
`locale`	string	—	Shared locale for templated/TTS channels.
`template_variables`	object	—	Shared template-variable bag (≤32 keys) for templated channels.

Response — a single envelope with batch totals plus one row per recipient (returned in submission order):

{
  "data": {
    "total": 3,
    "sent": 2,
    "failed": 1,
    "results": [
      { "recipient": "+14155552671", "status": "sent", "verification_id": "vrf_…", "channel": "sms" },
      { "recipient": "+14155550000", "status": "sent", "verification_id": "vrf_…", "channel": "sms" },
      { "recipient": "not-a-number", "status": "failed", "error": { "code": "INVALID_RECIPIENT", "message": "…" } }
    ]
  }
}

Each result row is one of:

sent — { recipient, status: "sent", verification_id, channel }
failed — { recipient, status: "failed", error: { code, message } }

Status codes — the HTTP status reflects the batch outcome so SDKs can branch on response.ok:

HTTP	Meaning
`201`	Every recipient was sent (`failed === 0`).
`207`	Partial success — at least one sent and at least one failed (Multi-Status).
`400`	Every recipient failed (`sent === 0`); inspect each row’s `error`.

Verifications

List verifications

GET /api/v1/verify/?limit=&cursor=&status=&channel= returns verification rows newest-first. limit is capped at 100; cursor resumes the next page. Filter on status (pending / approved / failed / expired — the cancelled outcome is produced only by POST /{id}/cancel and shows up in list/get rows but is not a filter value) and/or channel. Read the status enum from the response rows.

curl -G https://api.orbit.devotel.io/api/v1/verify/ \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  --data-urlencode "status=approved" \
  --data-urlencode "channel=sms" \
  --data-urlencode "limit=25"

{
  "data": [
    {
      "id": "vrf_9e4d7b81a4f24b3daf1b6c2d5e8f0a1b",
      "to": "+14155552671",
      "channel": "sms",
      "status": "approved",
      "attempts": 1,
      "created_at": "2026-08-27T21:40:12.541Z",
      "expires_at": "2026-08-27T21:50:12.541Z",
      "approved_at": "2026-08-27T21:41:03.882Z"
    }
  ],
  "pagination": {
    "limit": 25,
    "next_cursor": "eyJjcmVhdGVkX2F0IjoiMjAyNi0wOC0yN1QyMT…",
    "has_next": true,
    "total": 4,
    "total_capped": false
  }
}

Follow pagination.next_cursor until has_next is false. An empty filter page (e.g. channel=totp, against which send rows never exist) returns data: [] — non-delivery factor lifecycles live in sibling factor tables, not the verifications table.

Get one verification

GET /api/v1/verify/{id} returns the full row — including attempts (checks consumed) and expires_at — scoped to the caller’s organization (a cross-tenant id resolves to 404).

curl https://api.orbit.devotel.io/api/v1/verify/vrf_9e4d7b81a4f24b3daf1b6c2d5e8f0a1b \
  -H "X-API-Key: dv_live_sk_your_key_here"

{
  "data": {
    "id": "vrf_9e4d7b81a4f24b3daf1b6c2d5e8f0a1b",
    "to": "+14155552671",
    "channel": "sms",
    "status": "pending",
    "attempts": 0,
    "created_at": "2026-08-27T21:52:00.000Z",
    "expires_at": "2026-08-27T22:02:00.000Z"
  }
}

Cancel a pending verification

POST /api/v1/verify/{id}/cancel flips a pending row to cancelled via a compare-and-set, ends any fallback chain, and returns the updated row. A row already in a terminal state (approved / failed / expired) fails the CAS and returns 409 — so the cancel is safe to issue once; don’t retry it after a success in a fallback race.

curl -X POST https://api.orbit.devotel.io/api/v1/verify/vrf_9e4d7b81a4f24b3daf1b6c2d5e8f0a1b/cancel \
  -H "X-API-Key: dv_live_sk_your_key_here"

{
  "data": {
    "id": "vrf_9e4d7b81a4f24b3daf1b6c2d5e8f0a1b",
    "status": "cancelled",
    "channel": "sms",
    "to": "+14155552671"
  }
}

Aggregates

Method	Path	Purpose
`GET`	`/api/v1/verify/analytics`	Aggregate verification totals + channel breakdown
`GET`	`/api/v1/verify/conversion-anomaly`	Per-destination OTP conversion-anomaly (AIT / SMS-pumping) report

GET /api/v1/verify/analytics aggregates verifications over a rolling look-back window. Pass an optional window_days query parameter to size the window; the applied value is echoed back in the response. Query parameters

Field	Type	Default	Notes
`window_days`	integer	`30`	Rolling look-back window in days. Clamped to `1`–`90`.

Response

Field	Type	Notes
`total`	integer	Verification count within the window.
`by_status`	object	Per-status breakdown, `{ status: count }`. Codes that lapsed before a check are reported as `expired`.
`by_channel`	object	Per-channel breakdown, `{ channel: count }`.
`avg_verify_seconds`	number \| null	Mean time from send to approval, in seconds, over verified codes in the window. `null` when none were verified.
`window_days`	integer	The look-back window actually applied (after clamping).

GET /api/v1/verify/conversion-anomaly is the Verify Fraud Shield discovery signal for artificially-inflated traffic (AIT / SMS-pumping). It scores each destination prefix by its OTP completion rate (verified ÷ sent) over an optional window_days look-back (1–90, default 30): destinations converting far below the tenant baseline against a material send volume are flagged, and the response headlines an estimated carrier spend-at-risk (USD). The payload is

{ window_days, total_sent, total_verified, baseline_conversion_rate, flagged_destinations, estimated_spend_at_risk_usd, destinations[] }

, where each destination carries { prefix, sent, verified, conversion_rate, score, band, anomaly, estimated_spend_at_risk_usd }. Read-only and tenant-scoped. Query parameters

Field	Type	Default	Notes
`window_days`	integer	`30`	Rolling look-back window in days. Clamped to `1`–`90`.

Response

Field	Type	Notes
`window_days`	integer	The look-back window actually applied (after clamping).
`total_sent`	integer	Tenant-wide terminal OTP sends in the window.
`total_verified`	integer	Tenant-wide approved OTP checks in the window.
`baseline_conversion_rate`	number	Tenant-wide completion rate (`total_verified ÷ total_sent`), 0–1.
`flagged_destinations`	integer	Rows in `destinations` where `anomaly` is `true`.
`estimated_spend_at_risk_usd`	number	Sum of `estimated_spend_at_risk_usd` across the flagged rows.
`destinations`	object[]	Per-prefix breakdown, sorted by `score` descending (up to 50 rows).

Each destinations[] row carries:

Field	Type	Notes
`prefix`	string	Leading destination dial prefix (the geo bucket, e.g. `+447`).
`sent`	integer	Terminal OTP sends to this prefix in the window.
`verified`	integer	Sends the recipient actually completed.
`conversion_rate`	number	`verified ÷ sent`, 0–1.
`score`	integer	Composite anomaly score, 0 (clean) → 100, built from conversion shortfall vs the baseline plus an at-risk-volume term.
`band`	string	Coarse tier derived from `score`: `< 30` → `low`, `30–54` → `elevated`, `55–79` → `high`, `≥ 80` → `critical`.
`anomaly`	boolean	`true` when the prefix clears three gates: at least 20 sends, `conversion_rate` at or below 0.30, and at or below half the tenant baseline.
`estimated_spend_at_risk_usd`	number	Unverified sends priced at per-channel unit cost. Non-zero only when `anomaly` is `true`.

Reading the signal

curl -G https://api.orbit.devotel.io/api/v1/verify/conversion-anomaly \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  --data-urlencode "window_days=30"

{
  "data": {
    "window_days": 30,
    "total_sent": 5850,
    "total_verified": 2752,
    "baseline_conversion_rate": 0.4704,
    "flagged_destinations": 2,
    "estimated_spend_at_risk_usd": 90.1,
    "destinations": [
      {
        "prefix": "+2519",
        "sent": 620,
        "verified": 10,
        "conversion_rate": 0.0161,
        "score": 98,
        "band": "critical",
        "anomaly": true,
        "estimated_spend_at_risk_usd": 30.5
      },
      {
        "prefix": "+447",
        "sent": 1240,
        "verified": 48,
        "conversion_rate": 0.0387,
        "score": 94,
        "band": "critical",
        "anomaly": true,
        "estimated_spend_at_risk_usd": 59.6
      },
      {
        "prefix": "+1408",
        "sent": 3990,
        "verified": 2694,
        "conversion_rate": 0.6752,
        "score": 0,
        "band": "low",
        "anomaly": false,
        "estimated_spend_at_risk_usd": 0
      }
    ]
  }
}

Here the tenant baseline is a healthy 47%, but +2519 (Ethiopia) completes 1.6% of 620 sends and +447 (UK mobile) completes 3.9% of 1240 — both well inside the critical band (score ≥ 80). +2519 is flagged on a volume many tenants would call small, because the gates ask for 20+ sends, not a large absolute count. +447 dominates the headline: its 1192 wasted sends account for

59.60 of the

90.10 at risk, so block that prefix first and let +2519 follow. Blocking is a per-organization setting you own — add the prefix to your org’s blocked_prefixes override and subsequent sends to it are rejected; the report stays read-only.

Profiles

Profiles bundle the delivery rules for a send (allowed channels, code length, expiry, rate limit) under a single profileId. Reference a profile on /send with the profile’s id and the caller’s to/channel stay thin.

Create a profile

curl -X POST https://api.orbit.devotel.io/api/v1/verify/profiles \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "login-otp",
    "channels": ["sms"],
    "codeLength": 6,
    "expirySeconds": 300,
    "maxAttempts": 3,
    "rateLimitPerHour": 10,
    "templates": {
      "sms": "Your code is {{code}}"
    }
  }'

{
  "data": {
    "id": "vprof_4d8e9a1b7c2f0e5a6b8c9d0e1f2a3b4c",
    "name": "login-otp",
    "channels": ["sms"],
    "codeLength": 6,
    "expirySeconds": 300,
    "maxAttempts": 3,
    "rateLimitPerHour": 10,
    "status": "active"
  }
}

Update one field (PATCH)

curl -X PATCH https://api.orbit.devotel.io/api/v1/verify/profiles/vprof_4d8e9a1b7c2f0e5a6b8c9d0e1f2a3b4c \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "expirySeconds": 600 }'

{
  "data": {
    "id": "vprof_4d8e9a1b7c2f0e5a6b8c9d0e1f2a3b4c",
    "name": "login-otp",
    "channels": ["sms"],
    "codeLength": 6,
    "expirySeconds": 600,
    "maxAttempts": 3,
    "rateLimitPerHour": 10,
    "status": "active"
  }
}

List profiles

curl https://api.orbit.devotel.io/api/v1/verify/profiles \
  -H "X-API-Key: dv_live_sk_your_key_here"

{
  "data": [
    {
      "id": "vprof_4d8e9a1b7c2f0e5a6b8c9d0e1f2a3b4c",
      "name": "login-otp",
      "channels": ["sms"],
      "expirySeconds": 600,
      "maxAttempts": 3,
      "rateLimitPerHour": 10,
      "status": "active"
    }
  ]
}

Get / delete

# Get one profile
curl https://api.orbit.devotel.io/api/v1/verify/profiles/vprof_4d8e9a1b7c2f0e5a6b8c9d0e1f2a3b4c \
  -H "X-API-Key: dv_live_sk_your_key_here"

# Delete (204 — empty body)
curl -X DELETE https://api.orbit.devotel.io/api/v1/verify/profiles/vprof_4d8e9a1b7c2f0e5a6b8c9d0e1f2a3b4c \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -w "\nHTTP: %{http_code}\n"

Configs (alias of profiles)

/api/v1/verify/configs* is a frontend-facing alias of /profiles* — same controller, identical payloads and behaviour. The dashboard consumes /configs; either path may be used interchangeably from API or SDK callers.

Channels

POST /api/v1/verify/send accepts channel: sms, whatsapp, voice, email, viber, telegram, rcs, flashcall (delivery channels) plus the non-delivery / factor channels silent, sna, totp, push, magic_link, backup_code. rcs delivers the code through your tenant’s verified RCS Business Messaging agent (branded logo + checkmark, higher trust than plain SMS), failing closed with 503 PROVIDER_NOT_WIRED when no RCS provider is registered — so it slots cleanly into a fallback chain such as rcs → sms. flashcall delivers the code as the trailing digits of a missed call’s caller ID; the recipient submits those digits to /check. sna (Silent Network Authentication) verifies SIM possession through the CAMARA broker when you pass a device-bound device_token, returning status: "verified" with no OTP; without one it fails closed with 503 PROVIDER_NOT_WIRED. totp/push/backup_code short-circuit and steer you to the matching factor endpoints below. See the Verify overview for the full channel reference.

MFA factors

Possession-of-secret and phishing-resistant factors for end-tenant users. These factors carry no carrier delivery and no wallet deduct. Create/verify/delete require the verify:write scope.

These factors are API-only by design — there is no dashboard screen for them. TOTP, backup codes, passkeys (WebAuthn / FIDO2), and push are enrolled, verified, and revoked from inside your own application, where your end user is present to scan a QR code, complete a WebAuthn ceremony, or approve a push prompt on their device. Drive them straight from the endpoints below (or the SDK). The Verify dashboard covers OTP send/check, profiles, and analytics; the 2FA control under Settings → Security protects your Orbit login and is separate from these end-user factors.

TOTP (authenticator app)

Enroll a factor, render the otpauth:// URI as a QR code (or hand the secret to users who can’t scan), then verify its 6-digit codes. The create response also carries 10 single-use recovery codes — minted alongside the factor — so you can remediate a lost device on the spot.

Enroll

curl -X POST https://api.orbit.devotel.io/api/v1/verify/factors/totp \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "accountName": "user@example.com", "label": "iPhone" }'

{
  "data": {
    "factor_id": "vftotp_3a9b8c7d6e5f4a0b1c2d3e4f",
    "secret": "JBSWY3DPEHPK3PXP",
    "otpauth_uri": "otpauth://totp/Orbit%20by%20Devotel:user%40example.com?secret=JBSWY3DPEHPK3PXP&issuer=Orbit%20by%20Devotel&algorithm=SHA1&digits=6&period=30",
    "digits": 6,
    "period": 30,
    "algorithm": "SHA1",
    "recovery_codes": [
      "K3HQF-9PWMB",
      "R4TZC-1VWQX",
      "…8 more…"
    ]
  }
}

The secret and recovery_codes are surfaced once in this create response — subsequent GET /factors/totp returns metadata only, and plaintext codes are unrecoverable later (only their SHA-256 hashes are stored).

Verify a code

# 6-digit time code (or a recovery code — the service auto-discriminates)
curl -X POST https://api.orbit.devotel.io/api/v1/verify/factors/totp/vftotp_3a9b8c7d6e5f4a0b1c2d3e4f/verify \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "code": "482517" }'

{
  "data": {
    "status": "approved",
    "factor_id": "vftotp_3a9b8c7d6e5f4a0b1c2d3e4f",
    "method": "totp",
    "recovery_codes_remaining": 10
  }
}

A wrong code returns 400 INVALID_CODE. A consumed recovery code returns the same error — no enumeration.

Regenerate recovery codes / delete a factor

# Invalidate the old batch and mint 10 fresh codes (RETURNED ONCE)
curl -X POST https://api.orbit.devotel.io/api/v1/verify/factors/totp/vftotp_3a9b8c7d6e5f4a0b1c2d3e4f/recovery-codes/regenerate \
  -H "X-API-Key: dv_live_sk_your_key_here"

# Delete the factor (204 — empty body)
curl -X DELETE https://api.orbit.devotel.io/api/v1/verify/factors/totp/vftotp_3a9b8c7d6e5f4a0b1c2d3e4f \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -w "\nHTTP: %{http_code}\n"

Node.js snippet — enroll then verify

const API = "https://api.orbit.devotel.io/api/v1/verify";
const headers = {
  "X-API-Key": process.env.ORBIT_API_KEY,
  "Content-Type": "application/json",
};

// 1. Enroll — returns secret + otpauth:// URI + recovery codes ONCE
const enroll = await fetch(`${API}/factors/totp`, {
  method: "POST",
  headers,
  body: JSON.stringify({ accountName: "user@example.com" }),
}).then((r) => r.json());

console.log("Render this as a QR:", enroll.data.otpauth_uri);

// 2. Verify a 6-digit code from the user's authenticator app
const code = "482517"; // captured from the end user's input field
const check = await fetch(`${API}/factors/totp/${enroll.data.factor_id}/verify`, {
  method: "POST",
  headers,
  body: JSON.stringify({ code }),
}).then((r) => r.json());

console.log(check.data.status === "approved" ? "2-OK" : "deny");

Backup codes

Mint 10 single-use recovery codes when a user lost SMS / their authenticator device (the API broadcasts them once — the server stores SHA-256 hashes only and can’t re-read plaintext).

# Mint (RETURNED ONCE)
curl -X POST https://api.orbit.devotel.io/api/v1/verify/factors/backup-codes \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "accountName": "user@example.com", "label": "recovery" }'

{
  "data": {
    "factor_id": "vfbac_6d5c4b3a2e1f0d8c9e7f6a5b",
    "account_name_masked": "use***",
    "count": 10,
    "codes": [
      "2G7T4Z9H3KBF8XRT",
      "8Y3QN6WZ2KP4XHFM",
      "…8 more…"
    ]
  }
}

Consume one:

curl -X POST https://api.orbit.devotel.io/api/v1/verify/factors/backup-codes/vfbac_6d5c4b3a2e1f0d8c9e7f6a5b/verify \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "code": "S6MqxL6yED4q" }'

{
  "data": {
    "status": "approved",
    "factor_id": "vfbac_6d5c4b3a2e1f0d8c9e7f6a5b",
    "remaining_count": 9
  }
}

remaining_count lets your app prompt regeneration when fewer than 3 codes remain. A consumed / wrong code returns 400 INVALID_CODE. Delete the factor with DELETE /factors/backup-codes/{id} (204 — idempotent).

Verify Push

Register the device’s public key (ECDSA-P256 or Ed25519). The API returns a binding challenge the device must sign to activate the factor; without that signature the factor stays unverified and accepts no MFA challenges.

1. Register the device public key

curl -X POST https://api.orbit.devotel.io/api/v1/verify/push/factors \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "identity": "user_42",
    "friendlyName": "User42 iPhone",
    "algorithm": "ecdsa-p256",
    "publicKey": "04e8f7a2…a9cb31d5",
    "keyFormat": "raw",
    "deviceTokenId": "fcm_9a3xb8c2"
  }'

{
  "data": {
    "factorId": "vpf_8a7b6c5d4e3f2a1b0c9d8e7f",
    "status": "unverified"
  }
}

2. Issue a challenge

curl -X POST https://api.orbit.devotel.io/api/v1/verify/push/factors/vpf_8a7b6c5d4e3f2a1b0c9d8e7f/challenges \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "contextMessage": "Approve login from a new device?" }'

{
  "data": {
    "challengeId": "vch_2f1e8a9b01h2c3d4e5f6a7b8",
    "nonce": "mK3vN1bQ2p9gF4aT8uW6",
    "expiresAt": "2026-08-27T21:57:12.541Z"
  }
}

Dispatch the challenge to the device (FCM / APNs / Web Push — a dispatcher on the server picks the transport registered at factor creation). The response also carries signingString — the canonical <factorId>.<challengeId>.<nonce> concatenation — so naive clients don’t recompute it. The device signs that payload and posts back the signature.

3. Verify the signed nonce

curl -X POST https://api.orbit.devotel.io/api/v1/verify/push/challenges/vch_2f1e8a9b01h2c3d4e5f6a7b8/verify \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "signature": "MEUCIQDq3v…1m0s" }'

{
  "data": {
    "challengeId": "vch_2f1e8a9b01h2c3d4e5f6a7b8",
    "verdict": "approved",
    "factorStatus": "verified"
  }
}

Revoke a paired device

curl -X POST https://api.orbit.devotel.io/api/v1/verify/push/factors/vpf_8a7b6c5d4e3f2a1b0c9d8e7f/revoke \
  -H "X-API-Key: dv_live_sk_your_key_here"

{ "data": { "factorId": "vpf_8a7b6c5d4e3f2a1b0c9d8e7f", "status": "revoked" } }

Revocation is irreversible — the factor never accepts another challenge. Issued challenges and issued tokens already in flight keep their TTL.

Passkeys (WebAuthn / FIDO2)

Two ceremony pairs: registration (options → verify) and authentication (options → verify), plus revoke. The browser runs navigator.credentials / @simplewebauthn/browser; your app posts the resulting attestation or assertion. For the full browser-ceremony walkthrough — including the origin / rpId configuration — see Verify Passkey endpoint reference.

Registration — options

curl -X POST https://api.orbit.devotel.io/api/v1/verify/passkey/registration/options \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "identity": "user_42", "friendlyName": "User42 yubikey" }'

The response is a PublicKeyCredentialCreationOptionsJSON payload plus the challengeId you’ll echo on verify. Hand it to startRegistration() in the Browser.

Registration — verify

curl -X POST https://api.orbit.devotel.io/api/v1/verify/passkey/registration/verify \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "challengeId": "vpch_7b6a5d4c3e2f1a0b9c8d7e",
    "response": {
      "id": "Kz8…uQ",
      "rawId": "Kz8…uQ",
      "type": "public-key",
      "response": {
        "clientDataJSON": "eyJ0eXBl…",
        "attestationObject": "o2NmbXR…"
      }
    }
  }'

{
  "data": {
    "factorId": "vpkf_2c3b4a5f6d7e8g9h0i1j2k3l",
    "status": "verified"
  }
}

Authentication — options

curl -X POST https://api.orbit.devotel.io/api/v1/verify/passkey/authentication/options \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "identity": "user_42" }'

allowCredentials in the response carries this identity’s registered passkeys with transport hints — hand it to startAuthentication().

Authentication — verify

curl -X POST https://api.orbit.devotel.io/api/v1/verify/passkey/authentication/verify \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "challengeId": "vpch_8c7d6e5f4g3h2i1j0k9l8m",
    "response": { "id": "…", "rawId": "…", "type": "public-key", "response": { "…" } }
  }'

On success this bumps the factor’s signCount / lastUsedAt. A counter regression (cloned authenticator indicator) auto-revokes the factor. POST /verify/passkey/factors/{factorId}/revoke sets status: "revoked" and is idempotent.

Magic link

Email a signed, single-use link via channel: "magic_link". The public consume endpoint validates the HMAC + expiry, re-checks the recipient binding, and approves the underlying verification row.

Send

curl -X POST https://api.orbit.devotel.io/api/v1/verify/send \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "user@example.com",
    "channel": "magic_link",
    "code_length": 6
  }'

{
  "data": {
    "verification_id": "vrf_9e4d7b81a4f24b3daf1b6c2d5e8f0a1b",
    "channel": "magic_link"
  }
}

Consume (public, unauthenticated)

# Recipient's email client hits this; the API key is NOT required
curl -G https://api.orbit.devotel.io/api/v1/public/verify/magic-link/consume \
  --data-urlencode "token=eyJ2ZXJpZmljYXRpb25JZCI…"

{
  "data": {
    "verification_id": "vrf_9e4d7b81a4f24b3daf1b6c2d5e8f0a1b",
    "status": "approved"
  }
}

A malformed / expired / tampered token collapses to 400 INVALID_TOKEN with no reason differentiation (bad_HMAC vs expired look identical to the client), so an attacker can’t distinguish “wrong signature” from “elapsed” via the response.

Example — send and validate an SMS OTP

# 1. Send
curl -X POST https://api.orbit.devotel.io/api/v1/verify/send \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+14155552671",
    "channel": "sms",
    "code_length": 6,
    "max_attempts": 3,
    "locale": "en"
  }'

# Response: { data: { verification_id: "vrf_3f1c0b2a8e4d4f7a9c2b1e6d5a4c3b2a" } }

# 2. Check
curl -X POST https://api.orbit.devotel.io/api/v1/verify/check \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "verification_id": "vrf_3f1c0b2a8e4d4f7a9c2b1e6d5a4c3b2a", "code": "482517" }'

On a matching code the check endpoint returns 200 with { data: { verification_id: "vrf_3f1c0b2a8e4d4f7a9c2b1e6d5a4c3b2a", status: "approved" } }. Failures are not 200 bodies — they surface in the error envelope, where details.attempts_remaining counts the tries left:

Outcome	HTTP	Error code	Notes
Wrong code, attempts remaining	`422`	`VALIDATION_ERROR`	`details.attempts_remaining` counts the tries left
Max attempts exhausted	`422`	`VALIDATION_ERROR`	message `Maximum attempts exceeded`; the row is terminal
Code expired	`410`	`EXPIRED_TOKEN`	request landed after `expires_at`; the row is terminal

Codes have a small fixed number of attempts (default 3) before they’re exhausted. The check status enum is ["approved", "failed", "expired"] — failed and expired only ever appear inside the error envelope (or via GET /api/v1/verify/{id}), never as a 200 body. See Verify without an SDK for the full status model.

​Verify API

​Languages

​Send & check

​Bulk send

​Verifications

​List verifications

​Get one verification

​Cancel a pending verification

​Aggregates

​Reading the signal

​Profiles

​Create a profile

​Update one field (PATCH)

​List profiles

​Get / delete

​Configs (alias of profiles)

​Channels

​MFA factors

​TOTP (authenticator app)

​Enroll

​Verify a code

​Regenerate recovery codes / delete a factor

​Node.js snippet — enroll then verify

​Backup codes

​Verify Push

​1. Register the device public key

​2. Issue a challenge

​3. Verify the signed nonce

​Revoke a paired device

​Passkeys (WebAuthn / FIDO2)

​Registration — options

​Registration — verify

​Authentication — options

​Authentication — verify

​Magic link

​Send

​Consume (public, unauthenticated)

​Example — send and validate an SMS OTP

​See also