This guide walks you through configuring passkey authentication on your application using Prelude Auth. Passkeys can serve as an MFA step-up factor (the default) and, optionally, as a primary-factor passwordless sign-in method.
For the full conceptual reference — ceremony shape, security model, error catalogue — see the Passkey page.
Prerequisites
Before you start, make sure you have:
- A Prelude account with access to Prelude Auth
- An Application ID (
appID) — see Applications
- Your Management API key for backend calls
- A frontend served over HTTPS, or
http://localhost:<port> for local development — the WebAuthn API refuses any other origin
Set up passkey authentication
Configure the WebAuthn Relying Party identity for your app. The RP identity is shared across every passkey ceremony — changing it after credentials are registered invalidates them at the authenticator layer, so set it once per environment.
Create a passkey configuration
curl -X PUT https://api.prelude.dev/v2/session/apps/${APP_ID}/config/passkey \
-H "Authorization: Bearer ${MANAGEMENT_API_KEY}" \
-H "Content-Type: application/json" \
-d '{
"rp_id": "example.com",
"rp_name": "Example",
"allowed_origins": ["https://example.com", "https://app.example.com"],
"user_verification": "required",
"attestation_preference": "none",
"login_enabled": false
}'
| Field | Required | Description |
|---|
rp_id | Yes | The Relying Party identifier — the effective domain (no scheme, no port). Credentials are scoped to this RPID; changing it later breaks existing credentials. |
rp_name | Yes | Human-readable display name shown by authenticators during ceremonies. |
allowed_origins | Yes | List of permitted origins (scheme + host + optional port). Must be a superset of the RPID. For local development, http://localhost:<port> is accepted. |
user_verification | No | required (default), preferred, or discouraged. Use required for MFA so the ceremony proves something the user knows or is, not just possession. |
attestation_preference | No | none (default), indirect, direct, or enterprise. none is privacy-preserving and sufficient for most deployments. Required direct or enterprise when you want to enforce the AAGUID allowlist below. |
login_enabled | No | Defaults to false. Set to true to opt the app into primary-factor passwordless passkey login. See Enable passwordless login below. |
granted_scopes | No | Session scopes attached to the session minted by a primary-factor passkey login, mirroring the per-OAuth-provider and per-OTP granted scopes. Only applies to the passwordless login flow, not step-up. Empty grants no extra scopes. |
aaguid_allowlist | No | List of authenticator-model AAGUIDs (UUID strings) to accept. Empty list disables the filter. See Enterprise authenticator policy below. |
aaguid_blocklist | No | List of AAGUIDs to reject outright. Same shape as the allowlist. |
Declare verify_passkey on the step-up configuration
Add the step key to your step-up configuration and reference it from any scope whose challenge should require a passkey.curl -X PUT https://api.prelude.dev/v2/session/apps/${APP_ID}/config/stepup \
-H "Authorization: Bearer ${MANAGEMENT_API_KEY}" \
-H "Content-Type: application/json" \
-d '{
"step_keys": [
{ "key": "verify_passkey", "description": "WebAuthn second factor" }
],
"allowed_scopes": [
{
"scope": "transfer:write",
"mode": "direct",
"direct": {
"identifier_types": ["passkey"],
"status": "review",
"grant_mode": "single-use",
"granted_for": 600,
"steps": [
{ "order": 1, "key": "verify_passkey", "expiration_duration": 60 }
]
}
}
]
}'
passkey, so direct-mode entries select on it via identifier_types like any other identifier.To express a passkey-or-OTP fallback, list two direct entries on the same scope — the passkey-gated one first, the OTP fallback second. The runtime serves the first one whose identifier types the user holds:"allowed_scopes": [
{
"scope": "transfer:write",
"mode": "direct",
"direct": {
"identifier_types": ["passkey"],
"status": "review", "grant_mode": "single-use", "granted_for": 600,
"steps": [{ "order": 1, "key": "verify_passkey", "expiration_duration": 60 }]
}
},
{
"scope": "transfer:write",
"mode": "direct",
"direct": {
"identifier_types": ["email_address", "phone_number"],
"status": "review", "grant_mode": "single-use", "granted_for": 600,
"steps": [{ "order": 1, "key": "verify_sms", "expiration_duration": 300 }]
}
}
]
Enable passwordless login (optional)
Set login_enabled: true on the PasskeyConfig to opt the app into primary-factor passkey sign-in. While the flag is on, registration also requests a discoverable credential (residentKey: required) so the resulting passkey shows up in the browser’s autofill chip.
curl -X PUT https://api.prelude.dev/v2/session/apps/${APP_ID}/config/passkey \
-H "Authorization: Bearer ${MANAGEMENT_API_KEY}" \
-H "Content-Type: application/json" \
-d '{
"rp_id": "example.com",
"rp_name": "Example",
"allowed_origins": ["https://example.com"],
"user_verification": "required",
"attestation_preference": "none",
"login_enabled": true
}'
Existing credentials may not be discoverable. Turning login_enabled on does not retroactively migrate credentials registered while it was off — those were created with the WebAuthn default and platform passkeys (iCloud Keychain, Google, Microsoft, 1Password, …) are typically discoverable but older hardware security keys often are not. Affected users keep using step-up MFA without change, but to use the passwordless flow they need to register a new credential.
passkey_registration_failed after the flag flips on.
Enterprise authenticator policy (optional)
Restrict registration to specific authenticator models via the AAGUID allowlist / blocklist on the PasskeyConfig. Pairs with attestation_preference: "direct" or "enterprise" — with "none" most authenticators return an all-zeros AAGUID and the allowlist matches nothing.
curl -X PUT https://api.prelude.dev/v2/session/apps/${APP_ID}/config/passkey \
-H "Authorization: Bearer ${MANAGEMENT_API_KEY}" \
-H "Content-Type: application/json" \
-d '{
"rp_id": "example.com",
"rp_name": "Example",
"allowed_origins": ["https://example.com"],
"user_verification": "required",
"attestation_preference": "direct",
"aaguid_allowlist": [
"ee882879-721c-4913-9775-3dfcce97072a",
"08987058-cadc-4b81-b6e1-30de50dcbe96"
],
"aaguid_blocklist": [
"00000000-0000-0000-0000-000000000000"
]
}'
Subscribe to passkey lifecycle events (optional)
Three webhook events surface passkey activity for audit and user notifications:
| Event | When |
|---|
user.passkey.registered | A user completes the registration ceremony. The “we added a new passkey to your account — wasn’t you?” notification flow keys on this event. |
user.passkey.deleted | A user removes a credential (via the SDK or via the compromise-response /me/revoke?target=all flow). |
user.passkey.assertion_failed | An assertion fails to verify — bad signature, sign-count regression, expired login token, etc. Useful for brute-force / cloned-authenticator monitoring. |
curl -X POST https://api.prelude.dev/v2/session/apps/${APP_ID}/config/webhooks \
-H "Authorization: Bearer ${MANAGEMENT_API_KEY}" \
-H "Content-Type: application/json" \
-d '{
"url": "https://api.example.com/webhooks/prelude",
"events": ["user.passkey.registered", "user.passkey.deleted", "user.passkey.assertion_failed"]
}'
Surface passkey state in access tokens (optional)
The custom-claims pipeline exposes a has_passkey template input. Map it on your app’s claims configuration to let your frontend decide whether to prompt the user to enrol:
curl -X PUT https://api.prelude.dev/v2/session/apps/${APP_ID}/config/claims \
-H "Authorization: Bearer ${MANAGEMENT_API_KEY}" \
-H "Content-Type: application/json" \
-d '{
"mapping": {
"has_passkey": { "$input": "has_passkey", "$type": "bool" }
}
}'
What’s next?
Now that your backend is configured, integrate the frontend using the Web Passkey SDK guide. For the full reference — ceremony walk-through, security model, error catalogue, AAGUID policy details, and webhook payloads — see the Passkey page. 
