Verify passkey

No dashboard screen — passkeys are driven from your own application. A WebAuthn passkey is registered and used where the end user is present: your app requests options from these endpoints, runs the browser ceremony (navigator.credentials.create() / .get(), or the @simplewebauthn/browser helper), and posts the resulting attestation or assertion back to the matching verify endpoint. The Orbit dashboard covers OTP send/check, profiles, and analytics — it does not enroll or revoke passkeys on a user’s behalf. Retire a lost or rotated key from your app with POST /verify/passkey/factors/{factorId}/revoke.

Worked ceremony sequence

The five endpoints on this page are one lifecycle. The samples below run them in operator order — registration options → browser ceremony → registration verify → login options + login verify → revoke — with the real wire shapes at each step. Every JSON envelope below is a worked copy of the response, not the autogenerated "data": {} hull. Hand the returned options object to the browser verbatim — never re-serialize or mutate fields — and use @simplewebauthn/browser to keep the base64url handling honest.

1. Enroll — registration options

POST /api/v1/verify/passkey/registration/options returns the PublicKeyCredentialCreationOptionsJSON and a challengeId you submit back with the attestation.

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

The options endpoints are rate-limited at 20 requests/minute per tenant.

2. Enroll — browser ceremony + attestation verify

In the browser, run the ceremony with the exact options payload from step 1, then POST the serialized credential back within the TTL (default 300s, capped at 600):

import { startRegistration } from '@simplewebauthn/browser'

const attestation = await startRegistration({ optionsJSON: options })

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": "vpkchal_4e0f1a2b3c",
    "response": {
      "id": "S3vB1c9m2Xq7wYh0kZ2n5A",
      "rawId": "S3vB1c9m2Xq7wYh0kZ2n5A",
      "type": "public-key",
      "response": {
        "clientDataJSON": "eyJ0eXBlIjoid2VixWE1dGhuLmNyZWF0ZSI...",
        "attestationObject": "o2NmbXRkbm9uZWE...",
        "transports": ["internal"]
      }
    }
  }'

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

POST success returns 201 (not 200). backupEligible + backupState echo the authenticator’s BE/BS flags: false on backupEligible means the key lives on this one device — treat it accordingly. POST /api/v1/verify/passkey/authentication/options for the identity returns PublicKeyCredentialRequestOptionsJSON with that identity’s credentials hinted in allowCredentials:

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_1a2b3c", "ttlSeconds": 300 }'

{
  "data": {
    "challengeId": "vpkchal_8c3d9e1f22",
    "options": {
      "rpId": "verify.devotel.io",
      "challenge": "aB3xJ7fQ1tV9oLwH2yZk8cP4rTn6mSsD0aG5bF3iU2",
      "allowCredentials": [
        { "type": "public-key", "id": "S3vB1c9m2Xq7wYh0kZ2n5A", "transports": ["internal"] }
      ],
      "userVerification": "preferred"
    },
    "expiresAt": "2026-08-30T10:05:00.000Z"
  },
  "meta": {
    "request_id": "req_pks_auth_opts_03",
    "timestamp": "2026-08-30T10:02:00.000Z"
  }
}

import { startAuthentication } from '@simplewebauthn/browser'

const assertion = await startAuthentication({ optionsJSON: options })

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": "vpkchal_8c3d9e1f22",
    "response": {
      "id": "S3vB1c9m2Xq7wYh0kZ2n5A",
      "rawId": "S3vB1c9m2Xq7wYh0kZ2n5A",
      "type": "public-key",
      "response": {
        "clientDataJSON": "eyJ0eXBlIjoid2VixWE1dGhuLmdldCI...",
        "authenticatorData": "SZYN5YgOjGh0NBcPZHZgW4...",
        "signature": "MEUCIQDq0uW2kLfTqZ7oJ0bN...",
        "userHandle": "dXNfcjFhMmI3Yw"
      }
    }
  }'

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

On a passkey-counter regression — the W3C cloning signal — the factor is auto-revoked and the response carries cloningSuspected: true. The verify endpoints are rate-limited at 60 requests/minute per tenant.

5. Retire — revoke

POST /api/v1/verify/passkey/factors/{factorId}/revoke flips the factor to revoked. Idempotent — re-calling an already-revoked factor returns the same response:

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

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

After revocation, new login ceremonies against the factor are rejected with 409 / reason: "FACTOR_REVOKED".

Relying party and origin

WebAuthn binds every credential to a relying-party ID and an HTTPS origin, and the returned options payload carries both. The default RP is rpId: "verify.devotel.io" with origin https://verify.devotel.io.

Production apps on their own domain must be issued options whose rp.id is a registrable suffix of the page origin — browsers reject the ceremony otherwise, no network call ever fires. rpId must equal the origin’s host or be a parent domain of it (app.acme.com may use acme.com).
Local development: run on http://localhost — localhost is exempt from the HTTPS rule and ceremonies work there.
Never mutate the options object between the API response and the browser call; the attestation/assertion is bound to the exact challenge, RP ID, and origin inside it.

Server-side without an SDK helper

The Node SDK ships no typed passkey helper — walk the same ceremony server-side (test harnesses, CLI, CI smoke) with the generic orbit.request escape hatch:

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

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

const { data: reg } = 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' },
})

// hand `reg.options` to your browser/agent, collect the attestation, then:
const { data: factor } = await orbit.request<{
  challengeId: string
  factorId: string
  status: 'approved' | 'denied'
  credentialId: string
}>('POST', '/api/v1/verify/passkey/registration/verify', {
  data: { challengeId: reg.challengeId, response: attestation },
})

if (factor.status !== 'approved') {
  throw new Error(`passkey enrollment denied for ${factor.challengeId}`)
}

The browser ceremony step itself cannot move server-side — the authenticator lives with the user. Everything before and after it can.

Error surface

Failures arrive in the standard error envelope (meta.request_id included). Plan for these on the ceremony paths:

Status	`reason`	When it fires	Recovery
404	—	`challengeId`/factor unknown to this tenant	Re-issue `/options`; show a not-found state
409	`CHALLENGE_WRONG_TYPE`	registration challenge posted to the login verifier (or vice-versa)	Match the ceremony type to the verifier call
409	`CHALLENGE_TERMINAL`	challenge already used or denied	Challenges are single-use — re-issue `/options`
410	`CHALLENGE_EXPIRED`	attestation/assertion arrived after the TTL	Re-issue `/options` and retry the ceremony
409	`FACTOR_REVOKED`	login attempt on a revoked (or auto-revoked) factor	Route the user back through enrollment
422	`ATTESTATION_INVALID` / `ATTESTATION_UNVERIFIED`	RP/origin mismatch or corrupt attestation payload	Fix `rpId`/origin alignment; pass `options` through unmutated

A 422 on registration verify marks the challenge denied, so a malformed retry does not silently burn the pending ceremony — re-issue fresh options instead of looping on the same challengeId. Every passkey endpoint is authentication- and rate-limit-gated only — no extra scope — so issue dedicated keys for factor flows and restrict which callers can reach them. A factor created by one tenant is never visible to another.

API Reference

All Endpoints

Worked ceremony sequence

1. Enroll — registration options

2. Enroll — browser ceremony + attestation verify

5. Retire — revoke

Relying party and origin

Server-side without an SDK helper

Error surface

​Worked ceremony sequence

​1. Enroll — registration options

​2. Enroll — browser ceremony + attestation verify

​3. Login — authentication options

​4. Login — browser ceremony + assertion verify

​5. Retire — revoke

​Relying party and origin

​Server-side without an SDK helper

​Error surface

Worked ceremony sequence

1. Enroll — registration options

2. Enroll — browser ceremony + attestation verify

3. Login — authentication options

4. Login — browser ceremony + assertion verify

5. Retire — revoke

Relying party and origin

Server-side without an SDK helper

Error surface