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

This page carries more than 15 operations, so per the SDK language policy the full six-language group shows here for the operation you reach first — send + check — and every operation after that renders the cURL + Node.js (TypeScript) pair inside a <CodeGroup>, the floor the policy promises on every request sample. The pair recurs verbatim on every worked sample on this page — there is no bash-only fallback anywhere below. The core resources have typed SDK helpers (shown in the hero group here), so each language calls into verify.send / verify.check (Python, Node, Ruby, PHP) and Verify().Send / Verify().Check (Go); every later Node.js tab rides the untyped orbit.request() escape hatch with the same auth/retries and envelope, which is why it pairs with the cURL form instead of the wrap-everything <Tabs> strip.

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.

require "orbit_sdk"

client = OrbitSdk::Client.from_env  # reads ORBIT_API_KEY

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

checked = client.verify.check(verification_id: sent.dig("data", "id"), code: "123456")
puts checked.dig("data", "valid")

Vendor the SDK in your Gemfile — see the Ruby SDK for install and configuration.

<?php
use Devotel\Orbit\OrbitClient;

$client = OrbitClient::fromEnv();  // reads ORBIT_API_KEY

$sent = $client->verify->send(to: "+14155552671", channel: "sms");
$verificationId = $sent["data"]["id"];  // vrf_… — hand back into check below

$checked = $client->verify->check(verificationId: $verificationId, code: "123456");
var_dump($checked["data"]["valid"]);

Vendor the SDK via a Composer path repository — see the PHP SDK for install and configuration.

Every worked sample below this hero group pairs its cURL form with the Node.js orbit.request() escape hatch in one <CodeGroup> — the two most-used forms, side by side per operation. verify.check folds in wherever a worked call happens. Full SDK index at SDK quickstart.

Usage patterns — full six-language groups

The floor rule above (cURL + Node.js per operation) is never less than two languages. The headline operations every Verify integration must wire — Send, Check, Cancel, Get, List, and the aggregates — additionally each render the full six-language group below, one sample per operation. Trim as needed; nothing here is merely additive.

Send — full six-language group

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
  }'

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

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

const { data: sent } = await orbit.request("POST", "/verify/send", {
  jsonBody: { to: "+14155552671", channel: "sms", code_length: 6 },
});
console.log(sent.verification_id); // vrf_…

from orbit_sdk import OrbitClient

client = OrbitClient.from_env()  # reads ORBIT_API_KEY

sent = client.verify.send(to="+14155552671", channel="sms", code_length=6)
print(sent["data"]["id"])  # vrf_…

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_…

require "orbit_sdk"

client = OrbitSdk::Client.from_env  # reads ORBIT_API_KEY

sent = client.verify.send(to: "+14155552671", channel: "sms", code_length: 6)
puts sent.dig("data", "id")  # vrf_…

<?php
use Devotel\Orbit\OrbitClient;

$client = OrbitClient::fromEnv();  // reads ORBIT_API_KEY

$sent = $client->verify->send(to: "+14155552671", channel: "sms");
$verificationId = $sent["data"]["id"];  // vrf_…

The response is { "data": { "verification_id": "vrf_…", "channel": "sms" } } — see response shapes below for retry_count and error variants.

Check — full six-language group

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_9e4d7b81a4f24b3daf1b6c2d5e8f0a1b",
    "code": "482517"
  }'

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

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

const { data: checked } = await orbit.request("POST", "/verify/check", {
  jsonBody: {
    verification_id: "vrf_9e4d7b81a4f24b3daf1b6c2d5e8f0a1b",
    code: "482517",
  },
});
console.log(checked.status); // "approved" | "failed" | "expired"

from orbit_sdk import OrbitClient

client = OrbitClient.from_env()  # reads ORBIT_API_KEY

checked = client.verify.check(
    verification_id="vrf_9e4d7b81a4f24b3daf1b6c2d5e8f0a1b",
    code="482517",
)
print(checked["data"]["status"])

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

checked, err := client.Verify().Check(
    ctx,
    "vrf_9e4d7b81a4f24b3daf1b6c2d5e8f0a1b",
    "482517",
)
if err != nil {
    log.Fatal(err)
}
fmt.Println(checked.Data.Status)

require "orbit_sdk"

client = OrbitSdk::Client.from_env  # reads ORBIT_API_KEY

checked = client.verify.check(
  verification_id: "vrf_9e4d7b81a4f24b3daf1b6c2d5e8f0a1b",
  code: "482517",
)
puts checked.dig("data", "status")

<?php
use Devotel\Orbit\OrbitClient;

$client = OrbitClient::fromEnv();  # reads ORBIT_API_KEY

$checked = $client->verify->check(
    verificationId: "vrf_9e4d7b81a4f24b3daf1b6c2d5e8f0a1b",
    code: "482517",
);
var_dump($checked["data"]["status"]);

Cancel — full six-language group

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

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

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

const { data } = await orbit.request(
  "POST",
  "/verify/vrf_9e4d7b81a4f24b3daf1b6c2d5e8f0a1b/cancel",
);
// A row already terminal (approved / failed / expired) returns 409.

from orbit_sdk import OrbitClient

client = OrbitClient.from_env()  # reads ORBIT_API_KEY

cancelled = client.request(
    "POST",
    "/verify/vrf_9e4d7b81a4f24b3daf1b6c2d5e8f0a1b/cancel",
)
print(cancelled["data"]["status"])  # "cancelled"

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

cancelled, err := client.Request(
    ctx,
    "POST",
    "/verify/vrf_9e4d7b81a4f24b3daf1b6c2d5e8f0a1b/cancel",
    nil,
)
if err != nil {
    log.Fatal(err)
}
fmt.Println(cancelled.Data.Status) // "cancelled"

require "orbit_sdk"

client = OrbitSdk::Client.from_env  # reads ORBIT_API_KEY

cancelled = client.request(
  "POST",
  "/verify/vrf_9e4d7b81a4f24b3daf1b6c2d5e8f0a1b/cancel",
)
puts cancelled.dig("data", "status")  # "cancelled"

<?php
use Devotel\Orbit\OrbitClient;

$client = OrbitClient::fromEnv();  # reads ORBIT_API_KEY

$cancelled = $client->verify->cancel(
    verificationId: "vrf_9e4d7b81a4f24b3daf1b6c2d5e8f0a1b",
);
var_dump($cancelled["data"]["status"]);  # "cancelled"

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.

Get — full six-language group

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

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

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

const { data } = await orbit.request(
  "GET",
  "/verify/vrf_9e4d7b81a4f24b3daf1b6c2d5e8f0a1b",
);
console.log(data.status, data.attempts, data.expires_at);

from orbit_sdk import OrbitClient

client = OrbitClient.from_env()  # reads ORBIT_API_KEY

row = client.request(
    "GET",
    "/verify/vrf_9e4d7b81a4f24b3daf1b6c2d5e8f0a1b",
)
print(row["data"]["status"], row["data"]["attempts"])

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

row, err := client.Request(
    ctx,
    "GET",
    "/verify/vrf_9e4d7b81a4f24b3daf1b6c2d5e8f0a1b",
    nil,
)
if err != nil {
    log.Fatal(err)
}
fmt.Println(row.Data.Status, row.Data.Attempts)

require "orbit_sdk"

client = OrbitSdk::Client.from_env  # reads ORBIT_API_KEY

row = client.request(
  "GET",
  "/verify/vrf_9e4d7b81a4f24b3daf1b6c2d5e8f0a1b",
)
puts row.dig("data", "status"), row.dig("data", "attempts")

<?php
use Devotel\Orbit\OrbitClient;

$client = OrbitClient::fromEnv();  # reads ORBIT_API_KEY

$row = $client->verify->get(
    verificationId: "vrf_9e4d7b81a4f24b3daf1b6c2d5e8f0a1b",
);
var_dump($row["data"]["status"], $row["data"]["attempts"]);

List — full six-language group

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

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

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

const { data, pagination } = await orbit.request("GET", "/verify/", {
  query: { status: "pending", channel: "sms", limit: "25" },
});
// Follow pagination.next_cursor until pagination.has_next is false.

from orbit_sdk import OrbitClient

client = OrbitClient.from_env()  # reads ORBIT_API_KEY

page = client.request("GET", "/verify/", {
    "query": {"status": "pending", "channel": "sms", "limit": "25"},
})
for row in page["data"]:
    print(row["id"], row["status"])
# Follow page["pagination"]["next_cursor"] until has_next is false.

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

page, err := client.Request(
    ctx,
    "GET",
    "/verify/?status=pending&channel=sms&limit=25",
    nil,
)
if err != nil {
    log.Fatal(err)
}
for _, row := range page.Data {
    fmt.Println(row.ID, row.Status)
}
// Follow page.Pagination.NextCursor until HasNext is false.

require "orbit_sdk"

client = OrbitSdk::Client.from_env  # reads ORBIT_API_KEY

page = client.request(
  "GET",
  "/verify/?status=pending&channel=sms&limit=25",
)
page["data"].each { |row| puts row["id"], row["status"] }
# Follow page["pagination"]["next_cursor"] until has_next is false.

<?php
use Devotel\Orbit\OrbitClient;

$client = OrbitClient::fromEnv();  # reads ORBIT_API_KEY

$page = $client->request(
    "GET",
    "/verify/?status=pending&channel=sms&limit=25",
);
foreach ($page["data"] as $row) {
    echo $row["id"] . " " . $row["status"] . "\n";
}
// Follow $page["pagination"]["next_cursor"] until has_next is false.

Aggregates — full six-language group

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

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

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

const { data } = await orbit.request("GET", "/verify/analytics", {
  query: { window_days: "30" },
});
console.log(data.total, data.by_channel);

from orbit_sdk import OrbitClient

client = OrbitClient.from_env()  # reads ORBIT_API_KEY

agg = client.request("GET", "/verify/analytics", {
    "query": {"window_days": "30"},
})
print(agg["data"]["total"], agg["data"]["by_channel"])

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

agg, err := client.Request(
    ctx,
    "GET",
    "/verify/analytics?window_days=30",
    nil,
)
if err != nil {
    log.Fatal(err)
}
fmt.Println(agg.Data.Total, agg.Data.ByChannel)

require "orbit_sdk"

client = OrbitSdk::Client.from_env  # reads ORBIT_API_KEY

agg = client.request(
  "GET",
  "/verify/analytics?window_days=30",
)
puts agg.dig("data", "total"), agg.dig("data", "by_channel")

<?php
use Devotel\Orbit\OrbitClient;

$client = OrbitClient::fromEnv();  # reads ORBIT_API_KEY

$agg = $client->request("GET", "/verify/analytics?window_days=30");
var_dump($agg["data"]["total"], $agg["data"]["by_channel"]);

Swap analytics for conversion-anomaly in the path to reach the fraud report — the envelopes differ, the request shape is identical.

Response shapes

Every terminal send / check / cancel / get / list row carries the same vrf_… envelope; the shape below lists the fields a reader can rely on.

Success envelope — get / list rows

{
  "data": {
    "id": "vrf_9e4d7b81a4f24b3daf1b6c2d5e8f0a1b",
    "status": "approved",
    "channel": "sms",
    "to": "+14155552671",
    "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"
  }
}

Field	Type	Notes
`id`	string	`vrf_…` — hand back into `check` / `cancel` / `get`.
`status`	string	`pending` / `approved` / `failed` / `expired` / `cancelled`.
`channel`	string	Channel that delivered this terminal attempt.
`attempts`	integer	Check attempts consumed on this row.
`created_at` / `expires_at` / `approved_at`	ISO 8601	Timestamps for the row’s lifecycle; `approved_at` is absent until approval.

The send response carries the same envelope shape with the fallback chain embedded when one ran:

{
  "data": {
    "verification_id": "vrf_9e4d7b81a4f24b3daf1b6c2d5e8f0a1b",
    "status": "pending",
    "channel": "sms",
    "expires_at": "2026-08-27T21:50:12.541Z",
    "fallback_attempted": true,
    "fallback_attempts": [
      {
        "channel": "rcs",
        "index": 0,
        "ok": false,
        "errCode": "PROVIDER_NOT_WIRED",
        "errMessage": "No RCS provider registered for this tenant",
        "reason": "provider_rejected"
      },
      { "channel": "sms", "index": 1, "ok": true }
    ]
  }
}

The send result carries fallback_attempted / fallback_attempts only when a fallback chain ran (a chain over more than one channel is the gate); a single-channel send is wire-shape-identical to a chain-less send. Each fallback_attempts entry is { channel, index, ok, errCode?, errMessage?, reason? } — ok: false rows also carry reason (provider_rejected, fraud_blocked, transient_skip, internal_fault, …) and errCode naming the channel’s refusal. retry_count for a fully-worked chain is fallback_attempts.length — each entry burned one fallback hop before the row settled on the channel that delivers.

Error variants

Failures do not return 200 bodies — they surface in the error envelope, where error.code is the stable machine-readable discriminator:

HTTP	`error.code`	When it fires
`422`	`VALIDATION_ERROR`	Wrong code, retry-capable (`details.attempts_remaining` > 0). The row is terminal once `attempts_remaining` reaches 0 — stop retrying `check`.
`410`	`EXPIRED` / `EXPIRED_TOKEN`	Request landed after `expires_at`; the row is terminal. Start a new verification.
`429`	`RATE_LIMITED`	Per-recipient or per-org send gate tripped; back off per `details.retry_after_seconds`.
`409`	`VERIFICATION_TERMINAL`	`cancel` raced a terminal transition (`approved` / `failed` / `expired`); the row is final.
`503`	`PROVIDER_NOT_WIRED`	Channel not registered for this tenant (e.g. `rcs` with no RCS provider); don’t retry until it’s wired.

Treat EXPIRED and EXPIRED_TOKEN as interchangeable. The check and magic-link consume paths emit 410 EXPIRED_TOKEN today and the public-consume path emits 410 EXPIRED — a caller handling one 410 discriminator must handle the other, so accept both codes and the same remediation (start a new verification).

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"

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

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

const { data, pagination } = await orbit.request("GET", "/verify/", {
  query: { status: "approved", channel: "sms", limit: "25" },
});
// Follow pagination.next_cursor until pagination.has_next is false.

{
  "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"

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

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

const { data } = await orbit.request(
  "GET",
  "/verify/vrf_9e4d7b81a4f24b3daf1b6c2d5e8f0a1b",
);
console.log(data.status, data.attempts, data.expires_at);

{
  "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"

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

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

const { data } = await orbit.request(
  "POST",
  "/verify/vrf_9e4d7b81a4f24b3daf1b6c2d5e8f0a1b/cancel",
);
// A terminal row (approved / failed / expired) returns 409 — issue the
// cancel once.

{
  "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"

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

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

const { data } = await orbit.request("GET", "/verify/conversion-anomaly", {
  query: { window_days: "30" },
});
for (const d of data.destinations.filter((d) => d.anomaly)) {
  console.log(d.prefix, d.band, d.estimated_spend_at_risk_usd);
}

{
  "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}}"
    }
  }'

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

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

const { data: profile } = await orbit.request("POST", "/verify/profiles", {
  jsonBody: {
    name: "login-otp",
    channels: ["sms"],
    codeLength: 6,
    expirySeconds: 300,
    maxAttempts: 3,
    rateLimitPerHour: 10,
    templates: { sms: "Your code is {{code}}" },
  },
});
// Reference profile.id on /send — the caller's to/channel stay thin.

{
  "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 }'

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

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

const { data } = await orbit.request(
  "PATCH",
  "/verify/profiles/vprof_4d8e9a1b7c2f0e5a6b8c9d0e1f2a3b4c",
  { jsonBody: { 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"

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

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

const { data } = await orbit.request("GET", "/verify/profiles");

{
  "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"

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

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

// Get one profile
const { data: profile } = await orbit.request(
  "GET",
  "/verify/profiles/vprof_4d8e9a1b7c2f0e5a6b8c9d0e1f2a3b4c",
);

// Delete rides the same escape hatch — a 204 lands as an empty body
await orbit.request(
  "DELETE",
  `/verify/profiles/${profile.id}`,
);

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" }'

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

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

const { data: factor } = await orbit.request("POST", "/verify/factors/totp", {
  jsonBody: { accountName: "user@example.com", label: "iPhone" },
});
// factor.otpauth_uri renders as a QR; factor.secret + factor.recovery_codes
// surface ONCE here.

{
  "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" }'

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

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

// 6-digit time code (or a recovery code — the service auto-discriminates)
const { data } = await orbit.request(
  "POST",
  "/verify/factors/totp/vftotp_3a9b8c7d6e5f4a0b1c2d3e4f/verify",
  { jsonBody: { code: "482517" } },
);
console.log(data.status, data.recovery_codes_remaining);

{
  "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"

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

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

// Regenerate — invalidate the old batch, mint 10 fresh codes (RETURNED ONCE)
const { data: regenerated } = await orbit.request(
  "POST",
  "/verify/factors/totp/vftotp_3a9b8c7d6e5f4a0b1c2d3e4f/recovery-codes/regenerate",
);

// Delete the factor (204 — empty body)
await orbit.request(
  "DELETE",
  "/verify/factors/totp/vftotp_3a9b8c7d6e5f4a0b1c2d3e4f",
);

The enroll → verify sequence above is the whole flow — the paired Node.js tab in each <CodeGroup> rides the same orbit.request() escape hatch, so the sequence composes the way the cURL forms do.

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" }'

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

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

// Mint — codes RETURNED ONCE (hashes only are stored)
const { data: factor } = await orbit.request(
  "POST",
  "/verify/factors/backup-codes",
  { jsonBody: { 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" }'

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

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

const { data } = await orbit.request(
  "POST",
  "/verify/factors/backup-codes/vfbac_6d5c4b3a2e1f0d8c9e7f6a5b/verify",
  { jsonBody: { code: "S6MqxL6yED4q" } },
);
// data.remaining_count — prompt regeneration when fewer than 3 remain.

{
  "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"
  }'

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

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

const { data: factor } = await orbit.request("POST", "/verify/push/factors", {
  jsonBody: {
    identity: "user_42",
    friendlyName: "User42 iPhone",
    algorithm: "ecdsa-p256",
    publicKey: "04e8f7a2…a9cb31d5",
    keyFormat: "raw",
    deviceTokenId: "fcm_9a3xb8c2",
  },
});
// factor.status stays "unverified" until the binding challenge signs.

{
  "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?" }'

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

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

const { data: challenge } = await orbit.request(
  "POST",
  "/verify/push/factors/vpf_8a7b6c5d4e3f2a1b0c9d8e7f/challenges",
  { jsonBody: { contextMessage: "Approve login from a new device?" } },
);
// challenge.signingString is the canonical <factorId>.<challengeId>.<nonce>
// payload the device signs.

{
  "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" }'

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

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

const { data } = await orbit.request(
  "POST",
  "/verify/push/challenges/vch_2f1e8a9b01h2c3d4e5f6a7b8/verify",
  { jsonBody: { 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"

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

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

const { data } = await orbit.request(
  "POST",
  "/verify/push/factors/vpf_8a7b6c5d4e3f2a1b0c9d8e7f/revoke",
);
// Irreversible — the factor never accepts another challenge.

{ "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" }'

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

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

const { data: options } = await orbit.request(
  "POST",
  "/verify/passkey/registration/options",
  { jsonBody: { identity: "user_42", friendlyName: "User42 yubikey" } },
);
// Hand options + options.challengeId to startRegistration() in the browser.

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…"
      }
    }
  }'

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

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

const { data } = await orbit.request(
  "POST",
  "/verify/passkey/registration/verify",
  {
    jsonBody: {
      challengeId: "vpch_7b6a5d4c3e2f1a0b9c8d7e",
      // The browser's startRegistration() result, passed through verbatim
      response: attestation,
    },
  },
);

{
  "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" }'

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

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

const { data: options } = await orbit.request(
  "POST",
  "/verify/passkey/authentication/options",
  { jsonBody: { identity: "user_42" } },
);
// options.allowCredentials scopes the browser ceremony to this identity's
// passkeys.

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": { "…" } }
  }'

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

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

const { data } = await orbit.request(
  "POST",
  "/verify/passkey/authentication/verify",
  {
    jsonBody: {
      challengeId: "vpch_8c7d6e5f4g3h2i1j0k9l8m",
      // The browser's startAuthentication() result
      response: assertion,
    },
  },
);
// Success bumps the factor's signCount; a regression auto-revokes it.

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
  }'

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

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

const { data } = await orbit.request("POST", "/verify/send", {
  jsonBody: {
    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…"

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

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

// Public endpoint — the recipient's email client hits it with NO API key.
// Plain fetch, not the SDK: orb.request would attach the key.
const res = await fetch(
  "https://api.orbit.devotel.io/api/v1/public/verify/magic-link/consume?token=eyJ2ZXJpZmljYXRpb25JZCI…",
);
const body = await res.json();
console.log(body.data.status);

{
  "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" }'

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

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

// 1. Send
const { data: sent } = await orbit.request("POST", "/verify/send", {
  jsonBody: {
    to: "+14155552671",
    channel: "sms",
    code_length: 6,
    max_attempts: 3,
    locale: "en",
  },
});

// 2. Check
const { data: checked } = await orbit.request("POST", "/verify/check", {
  jsonBody: { verification_id: sent.verification_id, code: "482517" },
});
console.log(checked.status); // "approved"

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

​Usage patterns — full six-language groups

​Send — full six-language group

​Check — full six-language group

​Cancel — full six-language group

​Get — full six-language group

​List — full six-language group

​Aggregates — full six-language group

​Response shapes

​Success envelope — get / list rows

​Error variants

​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

​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