[Feature]: [Critical] WhatsApp mandatory passkey blocks all device linking — QR and pairing-code both fail

[adampalli]

Pre-flight

• I searched existing issues and this isn't already requested

Problem / motivation

Summary

WhatsApp has rolled out a mandatory passkey requirement for device linking
on some accounts. This completely breaks all OpenWA session linking methods
— QR scan and pairing code both fail. The bot is permanently disconnected
with no way to re-link.

Environment

• OpenWA: v0.7.14
• Engines tested: Baileys, whatsapp-web.js
• Deployment: Docker self-hosted (Oracle Cloud ARM64, Ubuntu)
• Phone: Android

What WhatsApp now requires

When attempting to link a device, WhatsApp shows:

"Create a passkey to log in — For security reasons, your account needs
a passkey to link devices"

Options: Create passkey / Don't link

• Tapping "Don't link" prevents any device from being linked at all
• Creating the passkey succeeds on the phone, but then shows
  "Continue on your other device" — and nothing happens on the
  OpenWA dashboard or any third-party client
• The passkey verification handshake requires biometric/screen-lock
  authentication on the receiving device, which headless/server-side
  clients cannot perform

QR scan flow (whatsapp-web.js and Baileys)

1. Session starts, QR generated successfully
2. Phone scans QR from OpenWA dashboard
3. Phone shows "Continue on your other device"
4. Session never reaches ready — stays at qr_ready
5. Baileys logs: repeated statusCode: 408 connection drops
6. whatsapp-web.js: QR keeps regenerating, session never authenticates

When scanning from web.whatsapp.com instead:

• Browser shows "Quick security check with Passkey → Continue"
• Tapping Continue does nothing
• Session never completes

Pairing code flow

1. POST /sessions/:id/pairing-code with {"phoneNumber": "91XXXXXXXXXX"}
2. Phone shows the 8-digit code entry screen
3. After entering phone number, WhatsApp shows
   "Continue on WhatsApp Web" — no code appears
4. Nothing progresses

Impact

• Cannot re-link any session after a force-logout
• Bot is permanently offline with no recovery path
• Affects both engines (whatsapp-web.js and Baileys)
• Affects both linking methods (QR and pairing code)

Expected behavior

OpenWA should handle the passkey verification handshake, or provide
an alternative linking path that doesn't require biometric authentication
on the server side.

Possible approaches

1. Implement the passkey/WebAuthn handshake in the whatsapp-web.js
   and Baileys engine adapters
2. Investigate whether WhatsApp Desktop's linking flow differs from
   the browser/headless flow at the protocol level, since Desktop
   also doesn't show the Quick security check with Passkey screen.
3. Investigate whether the passkey requirement can be avoided by
   spoofing a non-browser client context during QR/pairing flows

Additional context

This appears to be a phased rollout — not all accounts are affected yet.
Accounts that are affected have no workaround with current OpenWA versions.

Proposed solution

No response

Alternatives considered

No response

Scope

• I understand some features are limited by the underlying WhatsApp engine (e.g. interactive Buttons/List messages are not supported on whatsapp-web.js).

[rmyndharis]

Thanks for the very thorough write-up and screenshots — this is a real and painful change on WhatsApp's side.

To set expectations honestly: the passkey/WebAuthn challenge is enforced inside WhatsApp's linking handshake, which lives in the underlying engine libraries (whatsapp-web.js and Baileys), not in OpenWA. OpenWA passes the QR string and the pairing-code request straight through to those libraries and never touches the cryptographic linking frames, so there's no adapter-level place to answer a passkey challenge — a fix for the handshake itself has to come from the upstream libraries first.

There is one lever we do control that's worth testing. You noticed WhatsApp Desktop doesn't show the passkey screen, only browser/web clients do — which suggests the gate keys off the client type presented during linking. On the Baileys engine OpenWA currently identifies as a browser (Chrome); presenting a Desktop identity instead may route the account through the Desktop linking flow that skips the check. It's speculative — if the requirement is enforced per-account regardless of client, it won't help — but it's a cheap experiment, and we can expose it as an option to try.

We'll also track the upstream libraries for passkey/WebAuthn support and keep this issue open as the tracking point.

---

Update — 2026-07-02: please disregard the Desktop-identity experiment suggested above. The community has since tested exactly that (presenting a Desktop client identity, plus several browser variants) and it still returns 428 — client-type spoofing does not bypass the passkey gate. See the pinned summary comment for the confirmed account-side recovery path and the full analysis.

[ron007d]

+1

[Alexandre-Gavazzi]

✅ Confirmed workaround for accounts stuck in per-connection passkey mode

If your number is in the aggressive Shortcake mode (428 on every connection attempt, even after using the browser-auth bridge from @familymachlin-git / #2676), here's what worked for us today:

1. Delete your WhatsApp Business account entirely — Settings → Account → Delete my account.
2. Register the same number in WhatsApp Messenger (the regular app, not Business).
3. DO NOT reserve a username / link Instagram / link Facebook Business (these seem to be triggers of the aggressive rollout).

That's it. Pure Baileys 7.0.0-rc.13 with Browsers.appropriate('Chrome') → fresh QR → 515 (restart required, normal) → open → sending messages. No bridge needed.

Downsides: you lose groups, chat history, media. Groups don't restore even with backup (admins need to re-add you).

Theory: the per-connection passkey rollout seems to target Business accounts and accounts linked to Meta Business Suite. A fresh Personal registration on the same number escapes it — at least for now.

Tested today on a +55XXX number that had been in the 428 loop for 24h+. Same number, same SIM, just deleted the Business account and re-registered as Personal on WhatsApp Messenger.

Everything Diego (@diegofelipeee), @familymachlin-git, @gobeyondpty, @willianclic and @marcoscarraro shared here is gold and still works for accounts where you can complete the browser login. But if your browser itself refuses to complete login (Business accounts often can't), delete + recreate as Personal is the emergency exit.

---

⚠️ Before you nuke your account — MAKE A GROUP LIST

You will lose every group. Even the ones you administer. Even with backup restored. Admins need to re-add you one by one. Do this before deleting:

1. Open every group you care about → screenshot the group info (name + admin numbers).
2. If you're the sole admin of any group → promote someone else first, otherwise the group dies with your account.
3. Save contacts of key admins in a separate note — you'll need to DM them from the new account to be re-added.
4. Same for media / documents you might need later — export what matters, WhatsApp backup won't cover this reliably.

---

🪦 The graveyard of things we tried that FAILED miserably (~2 full days of pain)

Posting this so nobody else wastes time going down the same rabbit holes:

1. Baileys pure QR → 428 instantly.
2. Business → switch to WhatsApp Messenger (WITHOUT deleting) → still asks for passkey. The switch alone doesn't fix it, you have to nuke the account.
3. Browser ID spoofing — tried Browsers.macOS('Desktop'), Browsers.windows('Desktop'), Browsers.ubuntu('Chrome'), Browsers.macOS('Safari'), default appropriate('Chrome') → all 428.
4. Pairing code (8 digits) instead of QR → server closes the socket before you can even type it.
5. whatsapp-web.js (Puppeteer) → the modal "Quick security check with Passkey" returns "Something went wrong" forever.
6. Venom-bot → same thing, Puppeteer-based, same block.
7. WPPConnect → same, ditto.
8. webVersionCache: remote trick (@mehul-vekariya's fix) → unblocked it for some, for us reached the passkey modal but hit the same wall.
9. puppeteer-extra-plugin-stealth → removed the "controlled by automation" bar but the passkey check still failed.
10. Virtual WebAuthn authenticator via CDP (WebAuthn.addVirtualAuthenticator) → NotAllowedError — server rejects fake credentials (.get() with allowCredentials: [] requires a discoverable credential we don't have).
11. caBLE / Hybrid Transport (cross-device passkey via Bluetooth) → requires Bluetooth LE on the PC. No BT adapter = dead end. Even with BT, it's a manual click per connection — not viable in production.
12. Copy Chrome profile (7.8 GB!) to Puppeteer userDataDir → passkeys live in Google Password Manager and require active Sync — Sync doesn't survive the copy.
13. Puppeteer connect via --remote-debugging-port=9222 with the real Chrome → Chrome ignored the flag because another process was alive, port never opened.
14. Browser-auth bridge (@familymachlin-git technique) via Console script → creds extraction WORKED (Curve.verify OK, companion device correctly derived, 16 Noise candidates generated) → Baileys reached logging in... instead of attempting registration (progress!) → but server still killed the socket with 428 after ~200ms. Confirmed the aggressive rollout blocks even valid re-logins for Business accounts.
15. Cycling through Noise candidates [0..7] → all 428.
16. Fake network fingerprints, User-Agent shenanigans, hardcoded Web version pinning → nothing.
17. Waited for a maintainer response on the mainline fork/PR → all still in REVIEW_REQUIRED limbo.
18. Considered forking Baileys ourselves to implement Shortcake natively → mathematically impossible headless (WebAuthn requires a user gesture + real authenticator, that's the whole point of the spec).

At some point I was one Bluetooth USB dongle away from ordering it on Amazon just to test caBLE. Then I remembered @JoshAlfaro's comment saying only Business accounts were affected — deleted the account, recreated as Personal, connected on the first QR. 20 seconds. That easy.

Two days of engineering warfare killed by a 30-second setting change. 🪦 R.I.P. browser-auth bridge, we hardly knew ye.

— @Alexandre-Gavazzi

[rmyndharis]

Summary: recovery path + why there's no OpenWA-side fix

Huge thanks to @Alexandre-Gavazzi for the detailed write-up above — it's the most complete picture we've seen of this rollout, and it matches what we've found on our side.

The short version: this is a WhatsApp platform change, enforced inside the linking handshake before OpenWA (or any engine library) can participate. There is no headless fix — the passkey/WebAuthn step requires a real user gesture and authenticator by design, so no adapter, browser-identity spoof, or protocol trick can answer it. Independent testing in this thread has now ruled out every client-side workaround (browser/Desktop identity spoofing, pairing code, Puppeteer-based clients, virtual WebAuthn, caBLE, profile copying, and the browser-auth bridge — all still hit 428).

What does work today is account-side, not OpenWA-side. For accounts stuck in the aggressive per-connection passkey mode (428 on every attempt), the confirmed recovery is:

1. Delete the WhatsApp Business account (Settings → Account → Delete my account).
2. Re-register the same number in WhatsApp Messenger (the regular app, not Business).
3. Do not reserve a username, or link Instagram / Facebook Business — these appear to trigger the aggressive rollout.
4. Reconnect normally — a fresh QR links on the first try.

The gate appears to target Business accounts and accounts linked to Meta Business Suite; a fresh Personal registration on the same number escapes it. Treat this as works for now — WhatsApp may extend the rollout.

⚠️ Before you delete anything: you will lose groups, chat history, and media, and WhatsApp backup won't restore group membership — admins have to re-add you. Make a list of your groups and key admins first, and if you're the sole admin of any group, promote someone else before deleting, or the group dies with the account.

On our side: we're keeping this issue open and pinned as the tracking point, and we'll watch the upstream engine libraries for any passkey/WebAuthn developments. To correct the record: the "present a Desktop identity" experiment we suggested earlier has been tested by the community and does not work — we've retracted that suggestion.