Rapls Passkey Manual (Pro Edition)

Version 0.14.93 | PHP 8.2 or later | WordPress 6.0 or later | Requires Rapls Passkey (free) 0.12.0 or later, installed and active
The Pro edition builds on the full feature set of the free Rapls Passkey plugin, adding cross-device QR login, role-based passkey enforcement, recovery codes, email magic links, passwordless sign-up, adaptive step-up authentication, trusted device management, authenticator policy (FIDO MDS / AAGUID), security webhooks, adoption reports, multisite support, and more. For the free features and basic configuration, see the Free Manual.

Pro is an add-on: Rapls Passkey Pro is an add-on to the free Rapls Passkey plugin. First install and activate the free plugin from WordPress.org (rapls-passkey, 0.12.0 or later), then install the Pro edition on top of it. Until you enter a license, Pro imposes no restrictions, so the free plugin’s passkey login keeps working and nobody is locked out. Activate your license key under Settings > Rapls Passkey Pro > License to unlock the Pro features described in this manual.

Getting Started

License Activation

Rapls Passkey Pro is a one-time-purchase, license-based add-on distributed outside WordPress.org. When you purchase, a license key is issued immediately to the email address you registered. License keys take the form RPPK-XXXX-XXXX-XXXX-XXXX (four groups of four characters).

Steps from installation to license activation:

Install and activate the free Rapls Passkey plugin (0.12.0 or later).
Purchase from the Rapls Passkey Pro sales page and download rapls-passkey-pro.zip from the email you receive.
In the WordPress admin, go to Plugins > Add New > Upload Plugin, upload the ZIP, and activate Rapls Passkey Pro.
Open Settings > Rapls Passkey Pro > License.
Paste RPPK-XXXX-XXXX-XXXX-XXXX into the License Key field and enter the email address you used at purchase (the key is bound to that email).
Click “Activate.” When the status changes to Active, you’re done.

Screenshot of the license screen coming soon

Field	Description
License Key	The `RPPK-XXXX-XXXX-XXXX-XXXX` key from your purchase confirmation email
Email Address	The email address used at purchase. The key is bound to this address via HMAC, and verification only passes when both match
License Type	1-site or 5-site license. The license server determines the site limit
Status	Shows one of Active, Inactive, or Revoked
Deactivate (site migration)	Releases this site’s license when moving to another site. Once released, you can activate on a different site
Auto-Updates	With a valid license, you receive Pro updates from the private distribution source

About license verification: On activation, the plugin contacts the Rapls Works license API (https://raplsworks.com/wp-content/uploads/rapls-passkey/api.php). Your server must be able to make outbound HTTPS requests. If activation fails, check that allow_url_fopen or cURL is enabled. Verification results are cached for one day, and even if the license server is temporarily down, a license that was valid until just before continues to work through a 14-day grace period. Revoked licenses are rejected.

Site migration / staging: A license can be activated on 1 site (1-site license) or 5 sites (5-site license). To use it beyond the limit or to migrate a production site, “Deactivate” on the old site first, then “Activate” on the new one. When testing in a staging environment, likewise deactivate temporarily before moving.

Safe updates: Updates are delivered from the license server, not WordPress.org. Update checks are authenticated with your license, and the ZIP is fetched with a short-lived signed token (so the key never lingers in redirect or proxy logs). The downloaded ZIP is verified with SHA-256 before WordPress installs it. A “Check for updates” link is added to the plugin’s row in the plugins list.

Requirements

Item	Requirement
Free Rapls Passkey	0.12.0 or later, installed and active (required)
PHP	8.2 or later
WordPress	6.0 or later (latest stable recommended)
HTTPS	Required (except on localhost). Browsers reject WebAuthn without HTTPS
License Key	A Rapls Passkey Pro license key (1-site or 5-site)
Outbound HTTPS	Used for license verification, FIDO metadata fetching, and webhook delivery

Version dependency: Rapls Passkey Pro refuses to boot against free versions older than 0.12.0 and shows a notice in the admin (it does not cause fatal errors from missing classes or methods). Update the free plugin to the latest version first.

Quick Start (Recommended Order)

Activate the license — enter your key and email under Settings > Rapls Passkey Pro > License.
Encourage enrolment — enable the enrolment prompt to nudge users to register a passkey.
Prepare recovery methods — enable recovery codes and email login (magic link) first, so there’s a path when a passkey isn’t available.
Enforce gradually — choose target roles and set a grace period to require passkeys (start with a subset of roles).
Step-up — require passkey confirmation after a password login (start with adaptive).
Enforce passwordless — once adoption settles, consider disabling password login, blocking application passwords, and refusing password resets.
Set up operations — configure authenticator policy, webhooks, and adoption reports.

Important: Before enforcing passkeys or disabling password login, prepare recovery methods (recovery codes / email login) first. The last administrator, RAPLS_PASSKEY_BYPASS, and recovery codes prevent lockout, but we recommend trying one role first, confirming there are no problems, and then widening the scope.

This is a distinctive cross-device login where the computer displays a QR code, you scan it with your phone, and you approve with a passkey. Even if the computer has no passkey registered, you can sign in with the passkey on the phone in your hand. It works even when the devices are far apart.

How this differs from the free version: The free version also has the browser’s built-in cross-device feature (the “scan with your phone” flow that uses Bluetooth for nearby devices). What Pro adds is login through Rapls Passkey’s own QR channel, with relay protection via a confirmation code, and no dependence on proximity or Bluetooth.

How QR Login Works

On the login screen, choose “Approve on another device,” and the computer displays a QR code and a 4-digit confirmation code.
Scan the QR code with your phone’s camera, and the approval screen opens.
Enter the 4-digit confirmation code shown on the computer into your phone.
Approve with the phone’s passkey (Touch ID / Face ID / screen lock, etc.), and the login on the computer completes.

Screenshot of the QR login screen coming soon

Which passkeys can approve: Suspended passkeys cannot approve a QR login. In the usernameless (discoverable) flow, no allow-list narrowing occurs, so this explicit check is the only gate that rejects suspended passkeys.

The 4-Digit Confirmation Code (Relay / Phishing Protection)

The 4-digit code shown on the computer must be entered before you approve on the phone. This mechanism prevents attacks where an attacker relays their own login for a victim to approve.

A phishing victim sent only a link cannot see the attacker’s computer screen, so they cannot enter the code.
If you mistype the code, you can correct it without repeating the passkey prompt.
Repeated wrong entries invalidate the request.

The key idea: By requiring the approver to know “the value displayed on the attacker’s computer screen,” it blocks remote relays where the screen can’t be seen. This defeats the classic relay attack in which an attacker gets a victim’s passkey to approve the attacker’s own login.

Filters and the Same-Network Constraint

Filter	Default	Description
`rapls_passkey_pro/qr_confirmation_code`	Enabled	Lets you disable the 4-digit confirmation code. Disabling it weakens relay protection, so normally leave it on
`rapls_passkey_pro/qr_require_same_network`	Disabled	Requires the phone and computer to be on the same network. This automatically blocks remote relays, but prevents use across networks such as a mobile connection

Channel-state protection: The QR channel-state endpoint requires the computer’s secret cookie. Knowing the QR token alone does not let you learn whether the phone has approved.

Passkey Enforcement

Configure this under “Passkey Enforcement” in Settings > Rapls Passkey Pro. You can require users in chosen roles to register a passkey and migrate them in phases via a grace period.

Enforcement by Role

Setting	Default	Description
Target roles	None selected	Choose the roles required to register a passkey. If nothing is selected, enforcement is off
Grace period (days)	—	The number of grace days from when enforcement starts until users are required to enrol

Choosing roles: With no target role selected, enforcement is disabled. Start with just a subset of roles such as administrators or editors, confirm operations are fine, and then widen the scope.

Grace Period & Phased Rollout

When enforcement is enabled, users in target roles see a prompt encouraging passkey enrolment during the grace period. When the grace period ends, they are required to register a passkey after login. You can migrate existing users by deadline rather than burdening everyone at once.

Tip: Set the grace period to match your organization’s announcement window. If you enable the enrolment prompt (below) before enforcement begins, many users will register voluntarily during the grace period.

Lockout Prevention

The following safety valves are always in effect so that nobody is shut out.

The last administrator — the last administrator remaining on the site is exempt from enforcement.
Emergency bypass — defining define('RAPLS_PASSKEY_BYPASS', true); in wp-config.php temporarily lifts enforcement (break-glass).
Recovery codes — when a passkey isn’t available, users can recover with a recovery code.
Users who haven’t registered a passkey yet — users without a passkey are not locked out and are guided to enrol.

Note: When combining passkey enforcement with “Disabling Password Login” (below), always enable recovery codes or email login first. The safety valves above prevent a final lockout, but having an everyday recovery path in place greatly reduces the support burden.

Recovery & Alternative Logins

These are alternative logins and recovery methods for when a passkey isn’t available. None of them are passkeys themselves, so they aren’t as strong as a passkey sign-in. Enable them carefully, for recovery purposes.

Works alongside security plugins (SiteGuard, CloudSecure WP Security, Wordfence, Two-Factor): The image CAPTCHA of SiteGuard WP Plugin / CloudSecure WP Security is applied automatically to these alternative login screens too (recovery code, magic link, passkey sign-up). And if you use 2FA such as Wordfence Login Security or Two-Factor, magic-link and recovery-code logins stop at the two-factor challenge screen before an auth cookie is issued and complete only after the site’s own 2FA passes (free version 0.10.0+). A passkey sign-in (including the QR flow) is itself a second factor, so it isn’t challenged. You can add more CAPTCHA classes to the bridge with the rapls_passkey_pro/login_captcha_classes filter.

Recovery Codes

Issues single-use recovery codes. They are a break-glass method for when a passkey isn’t available, and can also be used from the “Can’t use your passkey?” link on the login screen.

Setting	Default	Description
Recovery codes	—	Generate single-use codes from the profile screen. Each code can be used only once
Number generated	—	How many codes to generate at once
Recovery alerts	Enabled	Notifies the user when codes are running low or used up, prompting a reissue. When code attempts on the login screen hit the limit (possible brute-force), the administrator is notified

Brute-force protection: Recovery-code attempts on the login screen have an always-on limit (5 per 15 minutes). When the limit is reached, the administrator is notified (duplicate alerts from the same IP are suppressed for a period).

Email Login (Magic Link)

Sends a one-time login link by email (disabled by default). It’s a fallback / recovery method for when a passkey isn’t available.

Setting	Default	Description
Email login (magic link)	Disabled	Sends a one-time login link by email
Allow for administrators too	Disabled	By default, magic links are not sent to administrators (so that compromising a mailbox alone can’t reach a high-value account). This setting allows administrators as well

Note: A magic link is not equivalent to a passkey. Because it lets anyone who can read the mailbox log in, sending to administrators is off by default. If you also use two-factor authentication (Wordfence Login Security / Two-Factor, etc.), magic-link and recovery-code logins stop at the two-factor challenge screen before an auth cookie is issued (requires free version 0.10.0 or later). A passkey sign-in (including the QR flow) is itself a second factor, so it is not challenged.

Lets users create a new account with a passkey from the login screen. The account is created only after the passkey verification succeeds (bot protection).

Setting	Default	Description
Passkey sign-up	Disabled	Shows a passkey sign-up link on the login screen

Prerequisite: WordPress’s “Anyone can register” option must be on. If it’s off (including when a security plugin such as Really Simple SSL forces it off), the sign-up link is not shown, and a note to that effect appears in settings. If saving the passkey fails, the half-created account is rolled back (deleted) and an error is returned. There’s also a daily per-IP limit.

Enforcing Passwordless

Adaptive Step-Up Authentication

After a password login, requires passkey confirmation once more. There are two modes: “adaptive,” which asks based on risk, and “two-factor,” which asks every time.

Mode	Value	Description
Only when risk is high (adaptive)	`adaptive`	Requires passkey confirmation only when logging in from an untrusted device and an unknown location (IP)
Every password login (two-factor)	`always`	Ignores risk signals and always layers passkey confirmation on top of the password. This is the classic “password + security key” configuration

The mode can also be set via the rapls_passkey_stepup_mode filter.

Held until confirmation: Sessions that haven’t completed step-up confirmation are held not only in the admin screen but also from the REST API, admin-ajax.php, admin-post.php, and XML-RPC. A high-risk password session cannot perform privileged operations from anywhere until passkey confirmation is complete. The plugin’s own public login routes remain reachable. Weak fallback logins (magic link / recovery code) do not clear a pending step-up nor mark a device as trusted. Only a genuine passkey assertion clears it.

Disabling Password Login

For users in enforced roles who already have a passkey, refuses interactive password login (fully passwordless).

Lockout prevention: The last administrator, RAPLS_PASSKEY_BYPASS, and recovery codes / email login prevent a shutout. Users who don’t have a passkey yet are exempt. XML-RPC password login continues to be refused by the existing gate.

Blocking Application Passwords / Refusing Password Reset

Closes the “back doors” that users meant to be passwordless still hold. Configure these under “Disabling Password Login” in Settings > Rapls Passkey Pro. Both are disabled by default and require “Disabling Password Login.”

Setting	Default	Description
Block application passwords too	Disabled	Application passwords are long-lived shared secrets that reach the REST API / XML-RPC without passing the interactive password gate. Block them to leave no phishable credentials. Because turning this on revokes API access, it’s off by default
Refuse “Lost your password?” too	Disabled	Closes the path (a password via email) by which anyone who can read the mailbox could issue a new password for an account meant to be passwordless. When on, users who lose a passkey recover with a recovery code or email login (single-use and auditable)

Same safety valves: Both settings apply the same exemptions as the password policy (not yet enrolled, the last administrator, RAPLS_PASSKEY_BYPASS), so nobody is locked out.

Device & Enrolment Management

Trusted Device Management

On the profile screen you can review and revoke the list of devices for which step-up no longer requires passkey confirmation. Once a device has confirmed, step-up stops asking it for a passkey (that’s the point), but it also means a device you’ve parted with (sold, lent, or used just once) silently retains the exemption.

Display / Action	Description
First trusted at	When the device was first trusted
Last access	When the device was last confirmed
Browser	The device’s browser. The device you’re currently viewing on is marked
Revoke trust	Revoke trust for individual devices or all of them (also forgets the remembered sign-in locations)

Privacy: Only an HMAC of the device ID is stored. Records logged by earlier versions also appear in the list, but timestamps that weren’t retained at the time are not shown.

Login Session Management

Review active login sessions (time, IP, browser) on the profile screen and end them individually, all others, or all. There’s also an option to automatically end other sessions on a passkey login.

“End other sessions on passkey login”: This setting works only on a passkey login, using the newly issued session token. It correctly ends other sessions even on a new device.

Enrolment Prompt

Shows a prompt after login encouraging users who don’t have a passkey yet to enrol. Even if dismissed, it reappears after a while.

Setting	Default	Description
Enrolment prompt	—	Shows a post-login enrolment prompt to users without a passkey. Reappears after a period even if dismissed
Admin-assisted enrolment	Disabled	Lets an administrator register a passkey on behalf of a user from the user’s profile screen (for handing over a pre-configured security key, or for in-person initial setup). Requires the `edit_user` capability, sends a notification email to the target account’s owner, and is recorded in the audit log

Authenticator Policy

Under “Authenticator Policy” in Settings > Rapls Passkey Pro, restrict the types of authenticators that can be registered.

FIDO Metadata Service (MDS)

Periodically downloads the FIDO Alliance’s authenticator metadata, verifies the BLOB signature (chained to the GlobalSign root certificate), and caches it. As a registration policy, you can choose one of the following.

Reject authenticators FIDO has flagged as problematic (revoked / compromised).
Allow only FIDO-certified authenticators (a minimum level of L1 / L2 / L3 can be set).

The policy applies only to authenticators that report an AAGUID. You can configure whether to allow authenticators not present in the metadata (such as synced passkeys). The settings screen shows the fetch status and a “Refresh now” button.

Setting	Description
Allow FIDO-certified only	Allows only authenticators that have FIDO certification
Certification level	The minimum certification level required (any level / L1 / L2 / L3)
Device-bound only	Rejects synced passkeys and allows only device-bound authenticators

Filters: The trust anchors to trust can be changed with rapls_passkey_pro/mds_root_certificates, and the fetch endpoint with rapls_passkey_pro/mds_endpoint. Metadata can also be refreshed via WP-CLI (wp rapls-passkey-pro mds-refresh).

AAGUID Allow / Deny Lists

Control the registration of specific authenticators with allow / deny lists of the AAGUID that identifies an authenticator model. This can be combined with the device-bound-only setting (reject synced passkeys).

Setting	Default	Description
AAGUID deny list	Empty	The AAGUIDs of authenticators to reject for registration (one per line)

Outputs /.well-known/webauthn so that passkeys with the same RP ID can be shared across multiple domains. Settings export / import round-trips the Related Origins list correctly too.

Notifications & Reports

Security Webhooks

Sends security events such as passkey registration, deletion, and sign-in to Slack / Microsoft Teams / generic JSON (for SOC / SIEM integration, non-blocking).

Setting	Description
Webhook URL	The destination URL. Slack / Teams URLs are effectively bearer secrets, so they are encrypted at rest
Format	Choose from Slack / Microsoft Teams / generic JSON

SSRF protection: Webhooks are sent with a safe HTTP client (it makes no requests to internal / loopback addresses and follows no redirects). This prevents SSRF that abuses an admin-configured URL. On settings export / import, the webhook URL round-trips in plaintext so the configuration can travel between sites.

Adoption Reports (Periodic Digest)

Emails administrators a summary of passkey adoption (enrolment rate by role and recent activity), weekly or monthly (disabled by default).

Setting	Default	Description
Periodic adoption report	Disabled	Sends adoption status by role, weekly / monthly
Recipient	Site admin email	You can specify recipients. If blank, it goes to the site admin email
Send now	—	Use “Send adoption report now” in the settings screen to send a preview

Privacy: The report contains only aggregate figures and no personally identifying information.

Reminders for Unenrolled Users

Periodically emails active users who haven’t registered a passkey, encouraging them to enrol (disabled by default).

Setting	Default	Description
Reminders for unenrolled users	Disabled	Emails users without a passkey, encouraging them to enrol
Target roles	—	You can target specific roles. Enforced roles are excluded (they receive enforcement guidance instead)

Send control: Once a day, it emails unenrolled users in turn (with a per-run limit). It leaves the configured interval before contacting the same person again. Each email includes a one-click unsubscribe link.

Adoption Analytics & Downgrade Detection

Shows enrolment rate by role and activity over the last 30 days as analytics. You can also set the audit-log retention period, and old records are deleted daily.

Downgrade-attack detection: When a user who has a passkey signs in with a password, you can notify the user (and optionally the administrator) by email (disabled by default). This helps detect phishing that steers users with “a password is enough” (a downgrade attack). It only detects; it does not block the login (to block, use “Disabling Password Login”). It targets only interactive password authentication; passkey / magic-link / recovery-code logins and application passwords are not included.

Operations & Automation

Multisite

Supports network-wide policy management and a shared RP ID. From the network admin, you can apply a common passkey policy to member sites.

Uninstall: On deletion in a multisite, each site’s options, cron, and transients are cleaned up.

Settings Export / Import

You can export / import the free and Pro settings as JSON. Use it to migrate from staging to production or to roll out to multiple sites at once.

Safe import: On import, only known setting keys are taken in, and they are re-run through the same per-field sanitizers as the settings form. An uploaded file cannot store values that bypass validation. Bugs from double-sanitizing (clearing the webhook URL or AAGUID deny list, double-encrypting the reCAPTCHA secret) have been fixed, and the webhook URL, AAGUID deny list, and Related Origins list round-trip correctly.

WP-CLI

Commands for server-side automation and break-glass recovery.

# Fetch and verify FIDO metadata
wp rapls-passkey-pro mds-refresh

# Generate recovery codes (count optional)
wp rapls-passkey-pro recovery-generate --user=<user> [--count=<n>]

# Invalidate recovery codes
wp rapls-passkey-pro recovery-clear --user=<user>

# Show adoption status by role and activity over the last 30 days
wp rapls-passkey-pro report

Tip: recovery-generate is also useful as a break-glass method when an administrator responds to a user who lost a passkey. The free version also has the wp rapls-passkey list/remove/stats commands (see the Free Manual).

Frequently Asked Questions

FAQ

Q: Can I install Pro without the free version?

A: No. Rapls Passkey Pro is an add-on to the free version. First install and activate the free Rapls Passkey (0.12.0 or later), then install Pro. If the free version is older than 0.12.0 or inactive, Pro refuses to boot and shows a notice in the admin.

Q: Can I use one license on multiple sites?

A: A 1-site license can be activated on 1 site; a 5-site license on 5 sites. For sites beyond the limit or when migrating a production site, “Deactivate” on the old site first, then “Activate” on the new one. The license is a one-time purchase with no expiry, and you can keep using it without renewing.

Q: If my license lapses (I don’t renew), do the Pro features stop?

A: No. Because it’s a one-time purchase, you can keep using the Pro features without renewing. One year of updates is included, and renewal from the second year onward is optional. Even if the license server is temporarily down, a license that was valid until just before continues to work through a 14-day grace period. Only revoked licenses are rejected.

Q: What is the 4-digit code in QR login for?

A: It’s relay / phishing protection. It prevents attacks where an attacker sends only a link to a login they’ve set up and gets the victim to approve it. Since the victim can’t see the attacker’s computer screen, they can’t enter the 4-digit code shown there, and the approval doesn’t go through. You can disable it with the rapls_passkey_pro/qr_confirmation_code filter, but normally leave it on.

Q: If I enforce passkeys, won’t users get locked out?

A: There are multiple safety valves so they don’t. The last administrator is exempt, define('RAPLS_PASSKEY_BYPASS', true); provides emergency relief, recovery codes and email login provide recovery, and users who don’t have a passkey yet are guided to enrol. We recommend enabling recovery methods before enforcement and trying a subset of roles first.

Q: What’s the difference between “Disabling Password Login” and “Blocking Application Passwords”?

A: “Disabling Password Login” refuses interactive password login (the login screen). Application passwords, on the other hand, are long-lived shared secrets that reach the REST API / XML-RPC without passing the interactive gate — a “back door” that remains even after disabling password login. To be fully passwordless, block both. Both use the same safety valves, so nobody is locked out.

Q: Do magic links or recovery codes bypass two-factor authentication (2FA)?

A: They don’t. If the site uses a 2FA plugin (Wordfence Login Security / Two-Factor, etc.) and the user has set up a second factor, magic-link and recovery-code logins stop at the two-factor challenge screen before an auth cookie is issued (requires free version 0.10.0 or later). A passkey sign-in (including the QR flow) is itself a second factor, so it isn’t challenged.

Q: When should I revoke a trusted device?

A: When you’ve sold or lent a device, or have one you used just once. Because step-up stops asking a once-confirmed device for a passkey, a device you’ve parted with keeps the exemption. From the trusted device list on the profile screen, revoke trust individually or for all devices (this also forgets the remembered sign-in locations).

Q: Does the authenticator policy (MDS / AAGUID) affect synced passkeys?

A: The MDS policy applies only to authenticators that report an AAGUID. You can configure whether to allow authenticators not present in the metadata, such as synced passkeys. Choosing “device-bound only” rejects synced passkeys. Making it too strict can prevent users from registering, so configure it with your target users’ authenticators in mind.

Q: Are webhook URLs stored securely?

A: Yes. Slack / Teams URLs are effectively bearer secrets, so they are encrypted at rest. Delivery uses a safe HTTP client that doesn’t go to internal / loopback addresses and follows no redirects, preventing SSRF. On settings export / import, they round-trip in plaintext so they can travel between sites.

Q: Do adoption reports or reminders contain personal information?

A: The adoption report contains only aggregate figures and no personally identifying information. Reminders for unenrolled users are sent to each user individually and include a one-click unsubscribe link. Enforced roles are excluded from reminders and receive enforcement guidance instead.