Passkeys (WebAuthn) for V2 Widgets

Passkeys let your users verify with the biometric they already use to unlock their device — Face ID, Touch ID, Windows Hello, or a screen lock — instead of waiting for a one-time code. Built on the WebAuthn standard and layered directly onto the V2 Widget you already know.

Instant verification — no code to wait for. When a returning user has a passkey on their device, the widget skips OTP delivery entirely: one biometric prompt and they're verified.

Passkeys require the V2 Widget

Passkeys are a V2 Widget capability only. They are not available on the V1.2 REST API or the legacy V1.0 REST API — those issue OTPs exclusively. If you authenticate over a REST API and want passkeys, move to the V2.0 Widget SDK first.

Recommended, backward-compatible, and opt-in

Passkeys are the recommended path forward for V2 Widgets. They are fully backward-compatible — if you change nothing, your widget keeps running OTP exactly as it does today. Turn passkeys on when you're ready, one iframe attribute at a time.

Why passkeys

Faster — instant. No SMS or WhatsApp round-trip. A returning user with a passkey on their device verifies in a single biometric prompt, with nothing to type and no code to wait for.

Higher conversion. Removing the "wait for a code, switch apps, copy, paste" loop eliminates the biggest source of drop-off in phone verification.

More secure. Passkeys are device-bound public-key credentials. There is no shared secret to phish, intercept, or replay — the private key never leaves the user's device.

Lower cost. A successful passkey authentication is billed at 60% of your OTP rate — so you save up to 40% per authentication. Enrollment is free, and only a successful authentication is ever charged.

Save up to 40% per authentication

When a user verifies with a passkey instead of an OTP, you pay 60% of your OTP rate for that authentication — a saving of up to 40%. Enrolling a passkey is free, and you are only billed on a successful passkey authentication. OTP authentications are unchanged.

Already using V2? Here's the one change

If you already run the V2 Widget, enabling passkeys is a single attribute on your iframe. Add the allow attribute so the embedded widget is permitted to invoke WebAuthn:

allow="publickey-credentials-get *; publickey-credentials-create *"

That's it. Here is the before → after for each common embed.

Add the allow attribute

<!-- Before -->
<iframe src="https://auth.akedly.io/auth?attemptId=..."></iframe>

<!-- After -->
<iframe
  src="https://auth.akedly.io/auth?attemptId=..."
  allow="publickey-credentials-get *; publickey-credentials-create *"
></iframe>

Prefer to scope the permission?

The wildcard * delegates WebAuthn to the iframe's origin. If you'd rather scope it explicitly to Akedly's auth origin, use:

allow="publickey-credentials-get https://auth.akedly.io; publickey-credentials-create https://auth.akedly.io"

That's the only change — nothing else moves

Do nothing and you keep OTP. The iframe URL stays …/auth?attemptId=… (only attemptId is required) — there are no new routes or parameters. Your postMessage, redirect, and webhook contracts are unchanged. There is nothing to do server-side: auth.akedly.io already serves the required Permissions-Policy and CSP frame-ancestors headers, so you only ever touch your own <iframe> tag.

How it works (end-user flow)

The passkey experience is woven into the existing widget flow. The user is never trapped on a passkey screen — a code is always one tap away.

  1. Captcha. The user passes the standard Cloudflare Turnstile check, exactly as today.
  2. Returning user with a passkey on this device. If the bound phone number already has a passkey on this device, the widget offers an optional "Use passkey" button. A "Use a code instead" option is always present alongside it.
  3. Everyone else. If there's no passkey for this device, the widget goes straight to normal OTP — no extra screens.
  4. Success. A passkey verification completes the attempt just like an OTP verification: same redirect, same webhook, same postMessage.
  5. After an OTP success. Once a user verifies with a code, the widget may show an optional, skippable "Enable passkey" prompt so their next verification can be instant.

Nobody ever gets trapped

If passkeys are unsupported on the device or browser, the user cancels, or the account isn't entitled, the widget silently falls back to OTP. There is no dead end and no error shown to the user.

New integrator guide

New to Akedly? Don't start here. Passkeys are an enhancement of the V2 Widget, not a standalone product — set the widget up first, and passkeys ride on the same attempt lifecycle with no extra steps.

Start on the V2 Widget guide

The complete setup — create a widget in the dashboard, create a server-side attempt with an HMAC signature, receive an iframeUrl, and open the iframe — lives on the V2.0 Widget SDK page, which now includes a dedicated Passkeys section covering exactly what to add for each embed surface. Build your V2 integration there with the allow attribute from day one, and passkeys light up automatically once your account is enabled — this page is the deeper passkey reference you return to afterward.

Handling the result

The result contracts are identical to standard V2 — consumers should key only on type === "AUTH_SUCCESS" and tolerate extra optional fields. A passkey success may add one optional field, verificationMethod: "passkey".

postMessage

  • Name
    type
    Type
    string
    Description

    "AUTH_SUCCESS". Key on this and nothing else — tolerate any extra optional fields.

  • Name
    attemptId
    Type
    string
    Description

    The original attemptId you created.

  • Name
    transactionId
    Type
    string
    Description

    The transaction identifier for this verification.

  • Name
    redirectUrl
    Type
    string
    Description

    Optional. Present when a frontend callback URL is configured.

  • Name
    timestamp
    Type
    string
    Description

    ISO 8601 timestamp of when authentication completed.

  • Name
    verificationMethod
    Type
    string
    Description

    Optional. "passkey" when the user verified with a passkey. Absent for OTP.

postMessage (passkey success)

{
  "type": "AUTH_SUCCESS",
  "attemptId": "attempt_a1b2c3d4e5f6...",
  "transactionId": "pkreq_9f8e7d6c5b4a...",
  "redirectUrl": "https://yourapp.com/auth/callback?status=success&...",
  "timestamp": "2026-01-16T12:05:30.123Z",
  "verificationMethod": "passkey"
}

Redirect

The success redirect query string is unchanged:

…?status=success&transactionId=…&attemptId=…×tamp=…&meta_*

Signed webhook

The webhook envelope is byte-compatible with the standard V2 webhook — same headers, same signing, same shape. For passkey verifications, note the following:

  • Name
    transactionId
    Type
    string
    Description

    For a passkey verification this is an opaque passkey request id, not an OTP transaction id. Treat it as opaque — store it and echo it back, but don't parse or assume its format.

  • Name
    verificationMethod
    Type
    string
    Description

    Optional. "passkey" when the user verified with a passkey.

  • Name
    channel
    Type
    string
    Description

    Absent for passkey verifications — there is no OTP delivery channel (WhatsApp / SMS / Email) involved. Don't depend on this field being present.

Verify the signature — unchanged

Passkey webhooks ship with the same HMAC-SHA256 svix-id, svix-timestamp, and svix-signature headers as every other backend callback. Verify the signature on the raw request bytes before trusting the payload, exactly as you do for OTP. See the webhook signing guide →

Platforms & surfaces

What you edit depends on how you embed the widget. The short version: web iframes add the allow attribute, full-page redirects need nothing, and native WebViews keep working unchanged (with an honest caveat below).

Enabling passkeys for your account

Passkeys are opt-in. They appear only when both of these are true:

  1. Passkeys are enabled for your account. During rollout, Akedly enables passkeys per account. Ask us to turn it on, or flip the toggle in your dashboard if it's available to you.
  2. The pipeline has passkeys on. Each pipeline carries a passkeyEnabled toggle (default: on). Leave it on to allow passkeys, or turn it off to keep a pipeline OTP-only.

Turn it on when you're ready

Everything here is fully backward-compatible. Until both the account and the pipeline are enabled, the widget runs OTP exactly as it does today. Add the allow attribute now, and passkeys will light up the moment your account is enabled — no further code changes needed.

FAQ & gotchas

Support & resources

Was this page helpful?