WhatsApp Passkey Required: What This Means and How to Fix It
What WhatsApp's passkey prompt actually is, and how to get past it during setup.
If you're mid-way through connecting a number to WaSMS and a screen pops up asking for a passkey, don't panic — this is WhatsApp's own security step, not something WaSMS is asking you to invent. Here's what it means and how to get past it.
What a passkey is
WhatsApp uses the word "passkey" for the extra security check it shows when a number is being verified, linked to a new device, or transferred. In most cases, this is the six-digit PIN you set up under WhatsApp's Two-Step Verification — WhatsApp just labels the prompt "passkey" or "PIN" depending on your app version and platform. On newer phones, WhatsApp is also rolling out biometric passkeys (fingerprint or face unlock) as a faster alternative to typing the PIN on that specific device.
Why WhatsApp asks for it
It's a protection against someone else re-registering your number on their device — a real risk for business numbers that get shared with a team, or numbers that were previously registered elsewhere. If Two-Step Verification is turned on for a number, WhatsApp will ask for the passkey/PIN any time that number is verified again, including when you connect it to a WaSMS gateway for the first time, or reconnect it after a gateway went offline.
Setting a passkey on your device
If you've never set one, open WhatsApp on the phone the number is registered to: Settings → Account → Two-step verification → Turn on, and set a 6-digit PIN. Add an email address when prompted — this is what lets you reset the PIN if you forget it, so don't skip it. If your phone supports it, you may also see an option to enable a device passkey (fingerprint/face) as a shortcut for that same PIN on that device.
Write the PIN down somewhere your team can find it, not just in one person's head. A forgotten passkey on a shared business number is one of the more common support tickets we see.
Entering it in WaSMS
During pairing — whether you're using WaSMS's local gateway on your own PC or the VPS gateway option — you'll scan a QR code first. If Two-Step Verification is already on for that number, WhatsApp will prompt for the PIN/passkey as a follow-up step right after the QR scan, directly inside the WhatsApp mobile app, not inside WaSMS itself. Enter it there, and the gateway pairing finishes automatically. If the QR step itself is what's stuck, that's a separate issue — see WhatsApp QR not loading.
What to do if you forget it
If you set an email during setup, use "Forgot PIN" on the verification screen — WhatsApp emails a reset link. Without an email on file, WhatsApp requires waiting out a lockout period (it grows with each attempt) before you can try again or set a new PIN. There's no way for WaSMS, or anyone but WhatsApp, to bypass this — it's WhatsApp's own account-level protection, working as designed. If the number's session was already active before the lockout, it should stay connected; the passkey only blocks new verifications, not an existing session.