{
  "data": {
    "factor_id": "vftotp_3f8b1c9d2e",
    "secret": "JBSWY3DPEHPK3PXPB63DEH7W5S6XKPKP",
    "otpauth_uri": "otpauth://totp/Orbit%20by%20Devotel:ada%40example.com?secret=JBSWY3DPEHPK3PXPB63DEH7W5S6XKPKP&issuer=Orbit%20by%20Devotel&digits=6&period=30",
    "digits": 6,
    "period": 30,
    "algorithm": "SHA1",
    "recovery_codes": [
      "K3HQF-9PWMB-7XTZK",
      "Q2LGD-8RNCA-4WYVE",
      "P5WMB-K3HQF-9ZXTQ",
      "M7XTK-Q2LGD-8RNCA",
      "Z9YVE-3GTEB-8NPKL",
      "3GTEB-8NPKL-Z9YVE",
      "H2PML-9QWZX-K3HQF",
      "9QWZX-H2PML-K3HQF",
      "V4ABC-2DLGM-8RNCA",
      "2DLGM-V4ABC-8RNCA"
    ]
  },
  "meta": {
    "request_id": "req_totp_create_01",
    "timestamp": "2026-08-30T10:00:00.000Z"
  }
}

{
  "data": {
    "factor_id": "vftotp_3f8b1c9d2e",
    "secret": "JBSWY3DPEHPK3PXPB63DEH7W5S6XKPKP",
    "otpauth_uri": "otpauth://totp/Orbit%20by%20Devotel:ada%40example.com?secret=JBSWY3DPEHPK3PXPB63DEH7W5S6XKPKP&issuer=Orbit%20by%20Devotel&digits=6&period=30",
    "digits": 6,
    "period": 30,
    "algorithm": "SHA1",
    "recovery_codes": [
      "K3HQF-9PWMB-7XTZK",
      "Q2LGD-8RNCA-4WYVE",
      "P5WMB-K3HQF-9ZXTQ",
      "M7XTK-Q2LGD-8RNCA",
      "Z9YVE-3GTEB-8NPKL",
      "3GTEB-8NPKL-Z9YVE",
      "H2PML-9QWZX-K3HQF",
      "9QWZX-H2PML-K3HQF",
      "V4ABC-2DLGM-8RNCA",
      "2DLGM-V4ABC-8RNCA"
    ]
  },
  "meta": {
    "request_id": "req_totp_create_01",
    "timestamp": "2026-08-30T10:00:00.000Z"
  }
}

The Verify factor suite end to end

Verify ships possession-of-secret MFA factors alongside OTP delivery: TOTP (authenticator apps), push (device public key + signed challenge), passkeys (WebAuthn / FIDO2), magic links, and backup codes. This guide walks the enroll → verify → revoke lifecycle for each one, so you can wire factor flows into your own application instead of assembling the endpoint tables yourself. The factor suite is API-only by design — it has no dashboard screen. Factors are enrolled, verified, and revoked from inside your application, where the end user is present to scan a QR code, run a WebAuthn ceremony, or approve a push prompt on their device. Drive the endpoints directly or through 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.) Factor endpoints carry no carrier delivery and no wallet deduct — they validate proof-of-possession against a server-side secret or device key pair. Every factor endpoint requires an authenticated request and is isolated to your organization: a factor created by one tenant is never visible to another.

1. Delivery channels vs factor channels

POST /verify/send accepts both a delivery channel and a factor channel value, but they mean different things. The first group delivers an OTP over a carrier; the second group proves possession without carrying an OTP. Delivery channels — sms, whatsapp, email, voice, viber, telegram, rcs, flashcall: The send generates a code and hands it to the channel provider. Phone-shaped recipients for phone channels, email-shaped recipients for email. These are also the only channels that make sense in a fallback chain. Factor channels — totp, push, passkey ceremonies, backup_code, plus the device-possession checks sna and silent, and magic_link: There is no OTP in transit and nothing to be delivered along a fallback chain. sna (Silent Network Authentication) and silent are network-level possession lookups rather than enrollable factors; totp, push, and backup_code are enrollable factors with their own lifecycle endpoints, covered below. magic_link replaces the typed code with a single-use email link (see §3.5).

2. Why `/verify/send` rejects a factor with 422

Sending channel: "totp", "push", or "backup_code" to POST /verify/send does not issue an OTP. The send endpoint short-circuits a factor-channel request with a typed 422 / 400 response that points you at the matching factor endpoint, because those channels are possession-of-secret factors with their own lifecycle — there is no carrier leg to send on, and no code to check with /verify/check afterward. To enroll or exercise a factor, call its dedicated endpoint directly (§3). To use a network-level possession check (sna, silent) or a magic link, those remain valid /verify/send channels — only the enrollable factors are rejected.

3. Enroll, verify, and revoke — per factor

Each subsection is the full lifecycle for one factor: enroll/create, exercise, revoke. The raw endpoint tables live in the Verify overview; the samples below put the calls in operator order with runnable curl plus the Node SDK generic orbit.request fallback (the SDK escape hatch, since these flows have no typed SDK helpers). All examples authenticate with an API key; http://localhost:4010 is only for local runs.

3.1 TOTP (authenticator app)

RFC 6238 factors compatible with Google Authenticator, Authy, 1Password, and similar apps. Codes are 6 digits on a 30-second step with ±1 step of clock-skew tolerance. 1. Enroll — POST /api/v1/verify/factors/totp. The response returns the otpauth:// URI for QR rendering, the base32 secret for manual entry, and 10 single-use recovery codes — all surfaced once (subsequent reads return metadata only):

cURL
Node.js SDK

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

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

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

const { data } = await orbit.request<{
  factor_id: string;
  secret: string;
  otpauth_uri: string;
  digits: number;
  period: number;
  algorithm: string;
  recovery_codes: string[];
}>('POST', '/api/v1/verify/factors/totp', {
  data: { accountName: 'ada@example.com', label: 'Ada phone' },
});
// Render data.otpauth_uri as a QR code; persist data.recovery_codes now.

{
  "data": {
    "factor_id": "vftotp_3f8b1c9d2e",
    "secret": "JBSWY3DPEHPK3PXPB63DEH7W5S6XKPKP",
    "otpauth_uri": "otpauth://totp/Orbit%20by%20Devotel:ada%40example.com?secret=JBSWY3DPEHPK3PXPB63DEH7W5S6XKPKP&issuer=Orbit%20by%20Devotel&digits=6&period=30",
    "digits": 6,
    "period": 30,
    "algorithm": "SHA1",
    "recovery_codes": [
      "K3HQF-9PWMB-7XTZK",
      "Q2LGD-8RNCA-4WYVE",
      "P5WMB-K3HQF-9ZXTQ",
      "M7XTK-Q2LGD-8RNCA",
      "Z9YVE-3GTEB-8NPKL",
      "3GTEB-8NPKL-Z9YVE",
      "H2PML-9QWZX-K3HQF",
      "9QWZX-H2PML-K3HQF",
      "V4ABC-2DLGM-8RNCA",
      "2DLGM-V4ABC-8RNCA"
    ]
  },
  "meta": {
    "request_id": "req_totp_create_01",
    "timestamp": "2026-08-30T10:00:00.000Z"
  }
}

2. Render the secret — show the otpauth_uri as a QR code (or the secret for manual entry) while the user is present. 3. Verify — POST /api/v1/verify/factors/totp/{factor_id}/verify with the current 6-digit code. The same endpoint also accepts a recovery code from the minted set; the response’s method tells you which path matched (totp or recovery_code):

cURL
Node.js SDK

curl -X POST "https://api.orbit.devotel.io/api/v1/verify/factors/totp/vftotp_3f8b1c9d2e/verify" \
  -H "X-API-Key: $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "code": "482913" }'

const { data } = await orbit.request<{
  status: 'approved';
  factor_id: string;
  method: 'totp' | 'recovery_code';
  recovery_codes_remaining: number;
}>('POST', '/api/v1/verify/factors/totp/vftotp_3f8b1c9d2e/verify', {
  data: { code: '482913' },
});

{
  "data": {
    "status": "approved",
    "factor_id": "vftotp_3f8b1c9d2e",
    "method": "totp",
    "recovery_codes_remaining": 10
  },
  "meta": {
    "request_id": "req_totp_verify_02",
    "timestamp": "2026-08-30T10:05:00.000Z"
  }
}

4. Recovery codes — POST /api/v1/verify/factors/totp/{factor_id}/recovery-codes/regenerate invalidates the prior set and re-mints 10 codes (surfaced once):

curl -X POST "https://api.orbit.devotel.io/api/v1/verify/factors/totp/vftotp_3f8b1c9d2e/recovery-codes/regenerate" \
  -H "X-API-Key: $ORBIT_API_KEY"

200

{
  "data": {
    "factor_id": "vftotp_3f8b1c9d2e",
    "recovery_codes": ["K3HQF-9PWMB-7XTZK", "…"]
  },
  "meta": {
    "request_id": "req_totp_regen_03",
    "timestamp": "2026-08-30T10:10:00.000Z"
  }
}

5. Revoke — DELETE /api/v1/verify/factors/totp/{factor_id} returns 204 No Content (idempotent — deleting a missing factor is safe):

curl -i -X DELETE "https://api.orbit.devotel.io/api/v1/verify/factors/totp/vftotp_3f8b1c9d2e" \
  -H "X-API-Key: $ORBIT_API_KEY"
# HTTP/1.1 204 No Content

TOTP writes (create, verify, delete, recovery-code regeneration) require the verify:write scope; dashboard session callers also need an owner, admin, or developer role. Reads (list) are gated by authentication and per-tenant rate limiting only.

3.2 Push (device public key)

Phishing-resistant push MFA via a device public key and a signed-challenge flow (mirroring Twilio Verify’s factor.type = "push"). The device holds the private key; the server keeps the public key and verifies signatures. 1. Create the factor — POST /api/v1/verify/push/factors registers the device’s public key and returns a binding challenge the device must sign to move the factor from unverified to verified:

cURL
Node.js SDK

curl -X POST "https://api.orbit.devotel.io/api/v1/verify/push/factors" \
  -H "X-API-Key: $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "identity": "user_1a2b3c",
    "friendlyName": "Ada iPhone 15",
    "algorithm": "ed25519",
    "publicKey": "mRmQY2fJ7h2T2FkQ+4jT7wEaQxw8RT0x2QGsl3yGpQ0=",
    "keyFormat": "raw",
    "deviceTokenId": "fcm_token_xyz123"
  }'

const { data } = await orbit.request<{
  factorId: string;
  identity: string;
  friendlyName: string;
  algorithm: string;
  status: 'unverified';
  createdAt: string;
  bindingChallenge: {
    challengeId: string;
    factorId: string;
    nonce: string;
    expiresAt: string;
    signingString: string;
    contextMessage: string | null;
  };
}>('POST', '/api/v1/verify/push/factors', {
  data: {
    identity: 'user_1a2b3c',
    friendlyName: 'Ada iPhone 15',
    algorithm: 'ed25519',
    publicKey: '<base64 key>',
    keyFormat: 'raw',
  },
});

{
  "data": {
    "factorId": "vfpush_7b3c9d1e2f",
    "identity": "user_1a2b3c",
    "friendlyName": "Ada iPhone 15",
    "algorithm": "ed25519",
    "status": "unverified",
    "createdAt": "2026-08-30T10:00:00.000Z",
    "bindingChallenge": {
      "challengeId": "vpchal_e44c9a7f13",
      "factorId": "vfpush_7b3c9d1e2f",
      "nonce": "zL9q5T8eW2rXs+fR0cV7gJkP3vH6dQbN1yU6mA0xEI=",
      "expiresAt": "2026-08-30T10:02:00.000Z",
      "signingString": "vfpush_7b3c9d1e2f.vpchal_e44c9a7f13.zL9q5T8eW2rXs+fR0cV7gJkP3vH6dQbN1yU6mA0xEI=",
      "contextMessage": null
    }
  },
  "meta": {
    "request_id": "req_push_create_01",
    "timestamp": "2026-08-30T10:00:00.000Z"
  }
}

2. Issue a challenge — POST /api/v1/verify/push/factors/{factorId}/challenges mints the nonce the device must sign. The signing string is <factor_id>.<challenge_id>.<nonce> — sign the raw bytes, never a JSON envelope:

cURL
Node.js SDK

curl -X POST "https://api.orbit.devotel.io/api/v1/verify/push/factors/vfpush_7b3c9d1e2f/challenges" \
  -H "X-API-Key: $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "contextMessage": "Approve sign-in to Acme app?" }'

const { data } = await orbit.request<{
  challengeId: string;
  factorId: string;
  nonce: string;
  expiresAt: string;
  signingString: string;
  contextMessage: string | null;
}>('POST', '/api/v1/verify/push/factors/vfpush_7b3c9d1e2f/challenges', {
  data: { contextMessage: 'Approve sign-in to Acme app?' },
});

{
  "data": {
    "challengeId": "vpchal_9d2e1c7b55",
    "factorId": "vfpush_7b3c9d1e2f",
    "nonce": "aB3xJ7fQ1tV9oLwH2yZk8cP4rTn6mSsD0aG5bF3iU2=",
    "expiresAt": "2026-08-30T10:07:00.000Z",
    "signingString": "vfpush_7b3c9d1e2f.vpchal_9d2e1c7b55.aB3xJ7fQ1tV9oLwH2yZk8cP4rTn6mSsD0aG5bF3iU2=",
    "contextMessage": "Approve sign-in to Acme app?"
  },
  "meta": {
    "request_id": "req_push_chal_02",
    "timestamp": "2026-08-30T10:05:00.000Z"
  }
}

3. Verify the signed nonce — the device signs the challenge; submit the signature with POST /api/v1/verify/push/challenges/{challengeId}/verify:

cURL
Node.js SDK

curl -X POST "https://api.orbit.devotel.io/api/v1/verify/push/challenges/vpchal_9d2e1c7b55/verify" \
  -H "X-API-Key: $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "signature": "MEUCIQDq0uW2kLfTqZ7oJ0bN..." }'

const { data } = await orbit.request<{
  challengeId: string;
  factorId: string;
  status: 'approved' | 'denied';
  approvedAt: string | null;
  attempts: number;
}>('POST', '/api/v1/verify/push/challenges/vpchal_9d2e1c7b55/verify', {
  data: { signature: '<device signature>' },
});

{
  "data": {
    "challengeId": "vpchal_9d2e1c7b55",
    "factorId": "vfpush_7b3c9d1e2f",
    "status": "approved",
    "approvedAt": "2026-08-30T10:05:12.000Z",
    "attempts": 1
  },
  "meta": {
    "request_id": "req_push_verify_03",
    "timestamp": "2026-08-30T10:05:12.000Z"
  }
}

4. Revoke the device — POST /api/v1/verify/push/factors/{factorId}/revoke un-pairs the device (after revoke, new challenges are rejected with 409 FACTOR_REVOKED; irreversible):

cURL
Node.js SDK

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

await orbit.request('POST', '/api/v1/verify/push/factors/vfpush_7b3c9d1e2f/revoke');

{
  "data": {
    "factorId": "vfpush_7b3c9d1e2f",
    "status": "revoked"
  },
  "meta": {
    "request_id": "req_push_revoke_04",
    "timestamp": "2026-08-30T10:20:00.000Z"
  }
}

Every push endpoint is gated by authentication and per-tenant rate limiting only — no verify:write scope is required, so restrict which API keys reach these flows accordingly.

3.3 Passkeys (WebAuthn / FIDO2)

Phishing-resistant passkey factors. The browser or OS handles the ceremony; the server only issues the options payload, verifies the attestation/assertion response, and keeps the credential state. 1. Start registration — POST /api/v1/verify/passkey/registration/options returns the PublicKeyCredentialCreationOptionsJSON the FE hands to navigator.credentials.create(). Hand the full options object straight through — no field mutation:

cURL
Node.js SDK

curl -X POST "https://api.orbit.devotel.io/api/v1/verify/passkey/registration/options" \
  -H "X-API-Key: $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "identity": "user_1a2b3c", "friendlyName": "Ada work laptop" }'

const { data } = await orbit.request<{
  challengeId: string;
  options: object; // PublicKeyCredentialCreationOptionsJSON
  expiresAt: string;
}>('POST', '/api/v1/verify/passkey/registration/options', {
  data: { identity: 'user_1a2b3c', friendlyName: 'Ada work laptop' },
});

{
  "data": {
    "challengeId": "vpkchal_4e0f1a2b3c",
    "options": {
      "rp": { "name": "Devotel Verify", "id": "verify.devotel.io" },
      "challenge": "6yC5vB8nT2sF9kLq7wE4gHjP3vN1dQbX0aU6mA0xEI0=",
      "user": { "id": "dXNlcj8xITBiMw", "name": "user_1a2b3c", "displayName": "Ada work laptop" },
      "pubKeyCredParams": [{ "type": "public-key", "alg": -7 }, { "type": "public-key", "alg": -257 }]
    },
    "expiresAt": "2026-08-30T10:05:00.000Z"
  },
  "meta": {
    "request_id": "req_pks_reg_opts_01",
    "timestamp": "2026-08-30T10:00:00.000Z"
  }
}

2. Complete the enrollment — run the browser’s navigator.credentials.create(), then POST /api/v1/verify/passkey/registration/verify with the attestation response. A verified attestation creates the factor:

cURL
Node.js SDK

curl -X POST "https://api.orbit.devotel.io/api/v1/verify/passkey/registration/verify" \
  -H "X-API-Key: $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "challengeId": "vpkchal_4e0f1a2b3c",
    "response": {
      "id": "S3vB1c9m2Xq7wYh0kZ2n5A",
      "rawId": "S3vB1c9m2Xq7wYh0kZ2n5A",
      "type": "public-key",
      "response": {
        "clientDataJSON": "eyJ0eXBlIjoid2UiCHAuY3JlYXRlIiw...",
        "attestationObject": "o2NmbXRkbm9uZSBvci0o...",
        "transports": ["internal"]
      }
    }
  }'

const { data } = await orbit.request<{
  challengeId: string;
  factorId: string;
  status: 'approved' | 'denied';
  identity: string;
  friendlyName: string;
  credentialId: string;
  aaguid: string | null;
  backupEligible: boolean;
  backupState: boolean;
  createdAt: string;
}>('POST', '/api/v1/verify/passkey/registration/verify', {
  data: { challengeId: 'vpkchal_4e0f1a2b3c', response: attestation },
});

{
  "data": {
    "challengeId": "vpkchal_4e0f1a2b3c",
    "factorId": "vfpk_9d2e1c7b55",
    "status": "approved",
    "identity": "user_1a2b3c",
    "friendlyName": "Ada work laptop",
    "credentialId": "S3vB1c9m2Xq7wYh0kZ2n5A",
    "aaguid": "08987059-4f0d-4a36-9f51-7f2a4b9c1a30",
    "backupEligible": true,
    "backupState": true,
    "createdAt": "2026-08-30T10:01:30.000Z"
  },
  "meta": {
    "request_id": "req_pks_reg_verify_02",
    "timestamp": "2026-08-30T10:01:30.000Z"
  }
}

3. Start authentication — POST /api/v1/verify/passkey/authentication/options returns the PublicKeyCredentialRequestOptionsJSON for navigator.credentials.get(), with the identity’s known credentials hinted in allowCredentials:

cURL
Node.js SDK

curl -X POST "https://api.orbit.devotel.io/api/v1/verify/passkey/authentication/options" \
  -H "X-API-Key: $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "identity": "user_1a2b3c", "ttlSeconds": 300 }'

const { data } = await orbit.request<{
  challengeId: string;
  options: object; // PublicKeyCredentialRequestOptionsJSON
  expiresAt: string;
}>('POST', '/api/v1/verify/passkey/authentication/options', {
  data: { identity: 'user_1a2b3c', ttlSeconds: 300 },
});

4. Verify the assertion — POST /api/v1/verify/passkey/authentication/verify validates the assertion and bumps the counter. On a counter regression (cloning signal) the factor is auto-revoked:

cURL
Node.js SDK

curl -X POST "https://api.orbit.devotel.io/api/v1/verify/passkey/authentication/verify" \
  -H "X-API-Key: $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "challengeId": "vpkchal_8c3d9e1f22",
    "response": {
      "id": "S3vB1c9m2Xq7wYh0kZ2n5A",
      "rawId": "S3vB1c9m2Xq7wYh0kZ2n5A",
      "type": "public-key",
      "response": {
        "clientDataJSON": "eyJ0eXBlIjoid2ViYXV0aG4uZ2V0Iiw...",
        "authenticatorData": "SZYN5YgOjGh0NBcPZHZgW4_krrmihjLHmVzr_oH0...",
        "signature": "MEUCIQDq0uW2kLfTqZ7oJ0bN...",
        "userHandle": "dXNfcjFhMmI3Yw"
      }
    }
  }'

const { data } = await orbit.request<{
  challengeId: string;
  factorId: string;
  status: 'approved' | 'denied';
  approvedAt: string | null;
  cloningSuspected: boolean;
}>('POST', '/api/v1/verify/passkey/authentication/verify', {
  data: { challengeId: 'vpkchal_8c3d9e1f22', response: assertion },
});

{
  "data": {
    "challengeId": "vpkchal_8c3d9e1f22",
    "factorId": "vfpk_9d2e1c7b55",
    "status": "approved",
    "approvedAt": "2026-08-30T10:02:15.000Z",
    "cloningSuspected": false
  },
  "meta": {
    "request_id": "req_pks_auth_verify_04",
    "timestamp": "2026-08-30T10:02:15.000Z"
  }
}

5. Revoke — POST /api/v1/verify/passkey/factors/{factorId}/revoke removes the passkey:

cURL
Node.js SDK

curl -X POST "https://api.orbit.devotel.io/api/v1/verify/passkey/factors/vfpk_9d2e1c7b55/revoke" \
  -H "X-API-Key: $ORBIT_API_KEY"

await orbit.request('POST', '/api/v1/verify/passkey/factors/vfpk_9d2e1c7b55/revoke');

{
  "data": {
    "factorId": "vfpk_9d2e1c7b55",
    "status": "revoked"
  },
  "meta": {
    "request_id": "req_pks_revoke_05",
    "timestamp": "2026-08-30T10:05:00.000Z"
  }
}

Like push, every passkey endpoint is gated by authentication and per-tenant rate limiting only — no extra scope.

3.4 Backup codes

Single-use recovery codes for users who lose their device and SMS access. These are the natural recovery leg for any of the factors above. 1. Mint — POST /api/v1/verify/factors/backup-codes returns 10 plaintext codes once; the server stores SHA-256 hashes only:

cURL
Node.js SDK

curl -X POST "https://api.orbit.devotel.io/api/v1/verify/factors/backup-codes" \
  -H "X-API-Key: $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "accountName": "user_1a2b3c", "label": "Ada recovery set" }'

const { data } = await orbit.request<{
  factor_id: string;
  codes: string[];
  count: number;
  generated_at: string;
}>('POST', '/api/v1/verify/factors/backup-codes', {
  data: { accountName: 'user_1a2b3c', label: 'Ada recovery set' },
});

{
  "data": {
    "factor_id": "vfbck_5e1f2a3b4c",
    "codes": [
      "8JR4WK2ZPF9GQL7D",
      "C3XVR5MN8B2ATY60",
      "7F1PKB9W3ZC0HQ2S",
      "E6TYRZB9Q4WCN30D",
      "9HU5QG3CPXLM4R9B",
      "D2VQZ4M8R7ACXL0K",
      "G4TCXN3LO0AS8FZ6BY",
      "L0SFB1VZ2DQ0YL1Q",
      "M1WCBLWZFQO2KK2Z",
      "P4DRPXPF4Z9JGM03"
    ],
    "count": 10,
    "generated_at": "2026-08-30T10:00:00.000Z"
  },
  "meta": {
    "request_id": "req_bck_create_01",
    "timestamp": "2026-08-30T10:00:00.000Z"
  }
}

2. Verify — POST /api/v1/verify/factors/backup-codes/{factor_id}/verify consumes one code. Each code can succeed at most once, and the response returns remaining_count so your UI can prompt regeneration before the user runs out:

cURL
Node.js SDK

curl -X POST "https://api.orbit.devotel.io/api/v1/verify/factors/backup-codes/vfbck_5e1f2a3b4c/verify" \
  -H "X-API-Key: $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "code": "8JR4WK2ZPF9GQL7D" }'

const { data } = await orbit.request<{
  status: 'approved';
  factor_id: string;
  remaining_count: number;
}>('POST', '/api/v1/verify/factors/backup-codes/vfbck_5e1f2a3b4c/verify', {
  data: { code: '8JR4WK2ZPF9GQL7D' },
});

{
  "data": {
    "status": "approved",
    "factor_id": "vfbck_5e1f2a3b4c",
    "remaining_count": 9
  },
  "meta": {
    "request_id": "req_bck_verify_02",
    "timestamp": "2026-08-30T10:15:00.000Z"
  }
}

3. Delete — DELETE /api/v1/verify/factors/backup-codes/{factor_id} removes the factor (204 No Content, idempotent):

curl -i -X DELETE "https://api.orbit.devotel.io/api/v1/verify/factors/backup-codes/vfbck_5e1f2a3b4c" \
  -H "X-API-Key: $ORBIT_API_KEY"
# HTTP/1.1 204 No Content

Backup-code writes require the verify:write scope (same posture as TOTP); reads are authentication-gated only.

3.5 Magic link

A magic link replaces the typed code with an email-delivered, single-use HTTPS link (Stytch / WorkOS / Auth0 parity). 1. Send — POST /api/v1/verify/send with channel: "magic_link" and an email to. Orbit emails a signed link; the <Note> in the Verify overview covers the same endpoint lookup pattern the /check resolver uses:

cURL
Node.js SDK

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": "ada@example.com", "channel": "magic_link"}'

const { data } = await orbit.request<{
  verification_id: string;
  channel: string;
  to: string;
  status: string;
}>('POST', '/api/v1/verify/send', {
  data: { to: 'ada@example.com', channel: 'magic_link' },
});

{
  "data": {
    "verification_id": "vfml_2b4c8e6a1d",
    "status": "sent"
  },
  "meta": {
    "request_id": "req_ml_send_01",
    "timestamp": "2026-08-30T10:00:00.000Z"
  }
}

2. Consume — the user’s click hits the public, unauthenticated endpoint GET /public/verify/magic-link/consume?token={token}, which approves the underlying verification on success and rejects tampered, expired, or already-used tokens:

curl "https://api.orbit.devotel.io/api/v1/public/verify/magic-link/consume?token=mltok_2hYfzi7pU3dF..."

200

{
  "data": {
    "status": "approved",
    "verification_id": "vfml_2b4c8e6a1d"
  },
  "meta": {
    "request_id": "req_ml_consume_02",
    "timestamp": "2026-08-30T10:02:00.000Z"
  }
}

The token is a constant-time HMAC-signed payload. There is nothing to enroll or revoke — the link is single-use per verification, so treat it as a send/check variant rather than a persistent factor.

4. Securing factor endpoints

The scope split matters for how you issue API keys:

TOTP and backup-code writes (create, verify, delete, recovery-code regeneration) require the verify:write scope. Dashboard session callers must also hold an owner, admin, or developer role.
TOTP and backup-code reads, and every push and passkey endpoint, are gated by authentication and per-tenant rate limiting only. They do not require an additional verify:write or verify:read scope, so any authenticated key scoped to the tenant can call them.

Issue dedicated keys for factor flows and restrict them to the callers you actually want enrolling and revoking factors. Tenant isolation applies throughout — a factor created by one tenant is never visible to another.

5. Data model and recovery

Secrets surface once. TOTP returns the base32 secret and otpauth:// URI on create; backup codes return the plaintext set on create. Persist them to the enrolling user’s device or your recovery flow at that moment — later reads return metadata only.
Hashes at rest. Backup codes (and TOTP recovery codes) are stored as SHA-256 hashes; verify compares hashes, never plaintext.
Recovery codes as the fallback leg. Pair any primary factor (TOTP, push, passkey) with a backup-code factor so a user who loses a device can still sign in. Monitor remaining_count on backup-code verify responses and prompt regeneration before exhaustion.
Revoke-a-device runbook. To cut off a lost or compromised device: revoke the push factor (/verify/push/factors/{id}/revoke) or passkey (/verify/passkey/factors/{id}/revoke), delete the TOTP factor, and — if the enrollment used backup codes — delete that factor or regenerate the TOTP recovery codes. Revocation endpoints are idempotent-safe to retry where noted (backup-code delete).

6. When to pick a factor over an OTP channel

OTP delivery channels and factors answer different threats:

Phishing-resistant possession — passkeys and the network-level sna check are not relayable through a phishing proxy in the way a typed OTP is. Prefer them for account-recovery and step-up flows where an attacker who can relay an OTP would otherwise win.
Device-bound approval — push proves a specific paired device answered, not just that someone read a code.
Nothing to relay — TOTP and backup codes keep the secret on both ends with no carrier leg, so no delivery provider, no SIM-swap exposure in transit, and no wallet deduct.
OTP still fits when the recipient has no enrolled device and you need to reach them over SMS, WhatsApp, email, or voice — the delivery channels and fallback chains cover that reach.

Pick the factor where a device or passkey exists; fall back to OTP delivery where it does not.

WhatsApp

Developer console

Contact center

Guides

Messaging Controls

Audience & Support Tools

MFA factor suite: TOTP, push, passkeys, magic links, and backup codes

The Verify factor suite end to end

1. Delivery channels vs factor channels

2. Why `/verify/send` rejects a factor with 422

3. Enroll, verify, and revoke — per factor

3.1 TOTP (authenticator app)

3.2 Push (device public key)

3.3 Passkeys (WebAuthn / FIDO2)

3.4 Backup codes

3.5 Magic link

4. Securing factor endpoints

5. Data model and recovery

6. When to pick a factor over an OTP channel

See also

​The Verify factor suite end to end

​1. Delivery channels vs factor channels

​2. Why /verify/send rejects a factor with 422

​3. Enroll, verify, and revoke — per factor

​3.1 TOTP (authenticator app)

​3.2 Push (device public key)

​3.3 Passkeys (WebAuthn / FIDO2)

​3.4 Backup codes

​3.5 Magic link

​4. Securing factor endpoints

​5. Data model and recovery

​6. When to pick a factor over an OTP channel

​See also

The Verify factor suite end to end

1. Delivery channels vs factor channels

2. Why `/verify/send` rejects a factor with 422

3. Enroll, verify, and revoke — per factor

3.1 TOTP (authenticator app)

3.2 Push (device public key)

3.3 Passkeys (WebAuthn / FIDO2)

3.4 Backup codes

3.5 Magic link

4. Securing factor endpoints

5. Data model and recovery

6. When to pick a factor over an OTP channel

See also