Verify integration without our SDK

Documentation Index

Fetch the complete documentation index at: https://orbit-docs.devotel.io/llms.txt

Use this file to discover all available pages before exploring further.

​

End-to-end flow

1. Your backend POSTs /api/v1/verify/send with { to, channel } → captures verification_id from the response.
2. Your frontend collects the code from the user via your own form. (We never need your UI — verification_id is opaque to the user.)
3. Your backend POSTs /api/v1/verify/check with { verification_id, code } → receives status: "approved" | "failed" | "expired".
4. Optionally subscribe to verification.* webhook events so you can react asynchronously instead of polling.

Customer app          Your backend                 Orbit API
─────────────────────────────────────────────────────────────────
 User taps "Send"  →  POST /verify/send       →  201 + verification_id
                      (stash id ↔ user_id)
 User types code   →  POST /verify/check      →  200 + status
                      (read status field)
                                              ↘  webhook delivery
                                                 (optional, async)

​

Authentication

export ORBIT_API_KEY="dv_live_sk_…"

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

{
  "data": {
    "verification_id": "vrf_3f1c0b2a8e4d4f7a9c2b1e6d5a4c3b2a",
    "status": "pending",
    "channel": "sms",
    "expires_at": "2026-05-24T12:10:00.000Z"
  },
  "meta": {
    "request_id": "req_8b2c1f4a…",
    "timestamp": "2026-05-24T12:00:00.000Z"
  }
}

// Pseudo-code — adapt to your stack.
await db.user_verifications.insert({
  user_id: currentUser.id,
  verification_id: response.data.verification_id,
  channel: response.data.channel,
  expires_at: response.data.expires_at,
  consumed: false,
});

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

{
  "data": {
    "verification_id": "vrf_3f1c0b2a8e4d4f7a9c2b1e6d5a4c3b2a",
    "status": "approved",
    "attempts_remaining": 0
  },
  "meta": {
    "request_id": "req_…",
    "timestamp": "2026-05-24T12:01:14.000Z"
  }
}

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid verification code",
    "details": { "attempts_remaining": 2 }
  },
  "meta": { "request_id": "req_…", "timestamp": "…" }
}

// verification.approved
{
  "type": "verification.approved",
  "data": {
    "verification_id": "vrf_3f1c0b2a…",
    "channel": "sms",
    "to": "+14155552671"
  }
}

​

Common patterns

​

Session expiry

​

Rate limits

• API-key rate limit — 20 /send calls / minute / key, 60 /check calls / minute / key. 429 with RATE_LIMIT_EXCEEDED.
• Org-wide per-recipient rate limit — defaults to 5 sends / hour / recipient (tenant-configurable). 429 with RATE_LIMIT_EXCEEDED.
• Per-recipient brute-force lockout — 30 wrong /check codes / recipient / hour locks out further attempts even if the attacker rotates verification_id. 429 with RATE_LIMIT_EXCEEDED once tripped. The lockout exists specifically to defeat the “spam /send to get fresh ids, then guess the 4–6 digit code” attack.

​

Fallback chain

​

Error envelope

{
  "error": {
    "code": "<MACHINE_READABLE_CODE>",
    "message": "<human-readable message>",
    "details": { /* error-specific, never the raw code */ }
  },
  "meta": { "request_id": "req_…", "timestamp": "…" }
}

​

Latency budget

​

Security checklist

• Send every request over HTTPS. The platform rejects plain HTTP.
• Keep X-API-Key server-side. Never expose it to the browser or a mobile binary. Use API-key IP allowlisting to constrain where it can be used from.
• Never log the raw code body field. Log verification_id instead. The platform itself stores only the SHA-256 hash and discards the raw code immediately after dispatch.
• Verify the X-Webhook-Signature header on every webhook delivery. Reject any body whose HMAC-SHA256 does not match.
• Treat verification_id as opaque. Do not parse the suffix to derive metadata — the entropy block has no semantic meaning and the prefix may change in future versions.

​

Observability — “did the user verify?”

​

What you do NOT need

• Our SDK — every endpoint described here works with any HTTP client. The Node SDK (@devotel/orbit-sdk) is a typed wrapper that calls these same routes; using it is optional.
• WebSockets or SSE — verification is request/response. Webhooks cover the async side.
• Background polling — subscribe to verification.approved and let the platform push the state change to you.
• A separate test environment — dv_test_sk_ keys hit the same endpoints and emit the same webhook events; only the underlying wallet ledger and provider dispatch are sandboxed.

​

Next steps

• Browse the full endpoint reference at API reference → Verify.
• Configure a profile (templates, channel chain, fraud caps) in Verify → Configuration before going live.
• Wire a webhook endpoint via Webhooks → Events.
• Read the Webhook events reference for the full verification.* payload schemas.