Passkeys on V2.0

Passkeys

Let returning users verify with the biometric that already unlocks their device — Face ID, Touch ID, Windows Hello, or a screen lock — instead of waiting for an OTP. Built on the WebAuthn standard and layered directly onto the V2 Widget you already know: same attempt lifecycle, same result contracts, one optional change to your embed. There is no shared secret to phish, intercept, or replay.

How passkeys work

Passkeys are woven into the existing widget flow — the user is never stranded on a passkey screen.

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 already has a passkey on this device, the widget offers an optional "Use passkey" button. "Use a code instead" is always shown alongside it.
3. Everyone else goes straight to normal OTP — no extra screens.
4. Success is identical to OTP — same redirect, same webhook contract, same postMessage.
5. After an OTP success, the widget may show an optional, skippable "Enable passkey" prompt so the next verification is instant.

V2 ceremonies ask the device for user verification as preferred; the V1.2 passkey ceremony requires it.

These short clips show both passkey ceremonies from the user's side:

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.

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.

<!-- 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>

// Before
<iframe src={iframeUrl} />

// After
<iframe
  src={iframeUrl}
  allow="publickey-credentials-get *; publickey-credentials-create *"
/>

<!-- Before -->
<iframe :src="iframeUrl" />

<!-- After -->
<iframe
  :src="iframeUrl"
  allow="publickey-credentials-get *; publickey-credentials-create *"
/>

// Before
const iframe = document.createElement('iframe')
iframe.src = iframeUrl

// After
const iframe = document.createElement('iframe')
iframe.src = iframeUrl
iframe.allow =
  'publickey-credentials-get *; publickey-credentials-create *'

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

Enabling passkeys for your account

Passkey availability depends on the current production configuration, account entitlement and pipeline settings. The checked-in backend defaults are not a promise about production access. Three gates decide whether the widget offers passkeys:

The pipeline control lives on the pipeline page, described in-product as "Let returning users verify with a device passkey and brand the experience":

View larger

Once passkeys are live, enrolled credentials and passkey activity are visible under Monitoring → Authentication → Passkeys (/admin/passkeys) in the dashboard:

View larger

Platforms & surfaces

What you change depends only on how you embed the widget. There are no new API routes, parameters, or SDK upgrades — the widget runs the passkey ceremonies itself.

Handling the result

The result contracts are identical to standard V2 — consumers should key only on type === "AUTH_SUCCESS" and tolerate extra optional fields. AUTH_SUCCESS is an optional hint: with a web Front-end Redirect URL the widget sends the user to that URL from inside the widget frame and does not post it, so treat the backend webhook, or a status lookup, as the source of truth.

postMessage

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

Redirect

The success redirect query string is unchanged:

…?status=success&transactionId=…&attemptId=…&timestamp=…&meta_*

Webhook signing

The webhook envelope is byte-compatible with the standard V2 webhook — same shape and signing mechanism. Signing is best-effort for widget callbacks: headers are present when signing succeeds, but a callback is still sent if signing fails. For passkey verifications, note the following:

Local vs on-device testing

Where the ceremony runs — and therefore the relying-party (RP) ID the passkey binds to — is controlled by ceremonyOrigin:

• Established local QA points the ceremony at the shared-cert dev auth-gateway origin (https://localhost:5174), binding to RP=localhost, which iOS Simulators and Android emulators accept. If the shared certificate files are absent, the dev server falls back to HTTP; configure ceremonyOrigin to the exact origin the server prints rather than mixing HTTP and HTTPS.
• Production / real devices use https://auth.akedly.io, binding to RP=akedly.io.

Per-platform prerequisites for the local loop: iOS Simulator → iOS 16+ and signed into iCloud; Android emulator → Google Play Services plus a configured screen lock (Credential Manager refuses without one); Web → any WebAuthn-capable browser.

Debugging tips

FAQ & gotchas

Support & resources

• V2.0 Widget SDK guide: /authentication/v2
• Webhook signing guide: /webhooks
• Dashboard: https://app.akedly.io
• Support: support@akedly.io