Passkey (WebAuthn)

​

Prerequisites

• A Prelude account with access to the Auth API
• An Application ID (appID) — see Applications
• Your Management API key for backend calls
• Step-up enabled on the application — see Step-Up Authentication
• A working login flow (users must be authenticated before they can register a passkey)
• The frontend served over HTTPS, or http://localhost:<port> for local development — the WebAuthn API refuses any other origin

​

How it works

​

Configure passkeys on the app

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
  }'

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"
    ]
  }'

curl -X POST 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": ["email_address", "phone_number"],
          "status": "review",
          "grant_mode": "single-use",
          "granted_for": 600,
          "steps": [
            { "order": 1, "key": "verify_passkey", "expiration_duration": 60 }
          ]
        }
      }
    ]
  }'

​

Fall back to OTP for users without a passkey

"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 }]
    }
  }
]

POST <your delegation hook>
{
  "scope_requested": "transfer:write",
  "user_id": "usr_...",
  "identifiers": [...],
  "has_passkey": true,
  "signals": {...},
  "metadata": {...}
}

​

Register a passkey

const { credential, alreadyRegistered } = await session.registerPasskey({
  username: "user@example.com",   // shown by the authenticator
  displayName: "User",            // optional, defaults to username
  nickname: "MacBook"             // optional, internal label
});

if (alreadyRegistered) {
  // This credential was already stored for the user — server returned a no-op success.
}

​

Surfacing passkey state to your frontend

{
  "mapping": {
    "has_passkey": { "$input": "has_passkey", "$type": "bool" }
  }
}

​

Manage registered passkeys

// "Manage your passkeys" — render the list.
const passkeys = await session.listPasskeys();

// Rename — no scope required.
await session.renamePasskey(credential.credential_id, "iPad");

// Delete — no scope required either.
await session.deletePasskey(credential.credential_id);

​

Compromise response — wipe all passkeys on session revoke

​

Use the passkey in step-up

let challengeId: string | undefined;

await session.requestStepUp({
  scope: "transfer:write",
  onChallenge: (info) => {
    challengeId = info.challengeId;
    if (info.currentStep !== "verify_passkey") {
      // Fall back to OTP / custom step UI.
      return;
    }
  }
});

if (challengeId) {
  await session.continueWithPasskey({ challengeId });
  // session is refreshed; the access token now carries "transfer:write"
}

import { isPasskeySupported } from "@prelude.so/js-sdk";

if (!isPasskeySupported()) {
  // Skip passkey entirely; offer SMS / email step instead.
}

​

Sign in with a passkey (primary factor)

• Discoverable credentials are required. A passkey registered through registerPasskey already qualifies — the authenticator stores the user handle locally on the device — so existing credentials light up the login flow without re-enrolment.
• Rate-limited. /login/passkey/begin is unauthenticated, so the bucket is keyed on the app id (default: 600/min). A leaked client SDK can’t spam begin ceremonies beyond the configured budget.
• Conditional UI. Pair the call with navigator.credentials.get({ ..., mediation: "conditional" }) (via the SDK) to power passkey autofill on the username field. The same assertion shape works for both eager and conditional flows.

​

What Prelude does

1. Begin: generates a 32-byte challenge, stashes the ceremony state under a single-use UUID in Redis (5-minute TTL, bound to the session), and returns the UUID as the registration_token. The state is GET-and-DEL’d on finish so the same token cannot be replayed. When login_enabled is on, the creation options also request residentKey: required so the resulting credential is discoverable.
2. Finish: validates the attestation / assertion against the cached challenge, the configured RPID, and the allowed origins. Rejects ceremonies whose origin or RPID do not match, and atomically consumes the session’s prld:passkey:write scope as part of the credential write.
3. Persists the credential (one row per user, per credential id) with the COSE-encoded public key, the authenticator-reported sign count, transports, AAGUID, and the backup-eligible / backup-state flags.
4. On every assertion, advances the sign count through a conditional update that rejects any non-monotonic value as a clone signal — surfaced as passkey_step_unavailable so the host app can fall back without exposing implementation details.
5. Anti-replay on the surrounding challenge token’s JTI, exactly like the OTP steps. The challenge token cannot be reused once the assertion has succeeded.

​

Constraints

​

Webhook events

​

Errors

​

Security recommendations

• Encourage backup credentials. A user with a single device-bound credential (hardware key, non-syncing platform passkey) cannot recover if they lose that device. Let them register more than one in your account-management UI.
• Treat sign-count regressions as security incidents. Prelude rejects them automatically, but if your fraud telemetry shows a credential repeatedly hitting passkey_step_unavailable after previously working, investigate.
• Rotate the Relying Party with care. Changing rp_id invalidates every existing credential. If you must, communicate it to users in advance and let them re-register before deprecating the old RPID.

​

What’s next?