Integrate WithPasskey

WithPasskey brokers WebAuthn ceremonies into a signed assertion your backend verifies against our JWKS. You never see a password, email, or private key — only a short-lived, pairwise-scoped identity proof.

Table of contents
  1. The model
  2. The sign-in flow
  3. Drop-in web component
  4. Node SDK — backend side
  5. Assertion claims
  6. Enrolling users
  7. Recovery
  8. Multiple origins, one account

The model

You register an application and receive a client_id (pk_…) and client_secret (sk_…). Your users hold passkeys bound to rpId withpasskey.xyz — one credential works on every origin you verify. Each user gets a different pairwise sub per application, so identities cannot be correlated across sites.

The sign-in flow

  1. Browser → GET /authorize?client_id&redirect_uri&response_type=code&code_challenge&code_challenge_method=S256 (state + nonce optional)
  2. The broker validates client status + verified redirect origin, then hosts the passkey ceremony
  3. On success the browser returns to your redirect_uri with a one-time code (pkc_…, 60s) and your state
  4. Your backend exchanges the code at POST /v1/token with client_secret + the PKCE code_verifier
  5. You receive a signed ES256 assertion (120s TTL) — verify it against /.well-known/jwks.json, then create your own session

The assertion is proof the ceremony happened — it is not a session and it is not refreshable. Mint whatever session your app needs from the verified claims.

Drop-in web component

PKCE + state + nonce handled for you
<script type="module" src="https://api.withpasskey.xyz/vendor/withpasskey.js"></script>

<withpasskey-login
  api-url="https://api.withpasskey.xyz"
  client-id="pk_live_…"
  redirect-uri="https://your.app/callback">
</withpasskey-login>

On the callback, consumePending() returns the stored codeVerifier/state/nonce (one-shot, sessionStorage). Verify state matches the returned ?state, then POST the code + verifier to your backend.

your /callback — browser side
import { consumePending } from '@withpasskey/sdk-web';

const q = new URLSearchParams(location.search);
const pending = consumePending();
if (!pending || pending.state !== q.get('state'))
  throw new Error('state mismatch');

await fetch('/api/exchange', {
  method: 'POST',
  body: JSON.stringify({
    code: q.get('code'),
    codeVerifier: pending.codeVerifier,
    nonce: pending.nonce
  })
});

Node SDK — backend side

@withpasskey/sdk-node
import { createClient } from '@withpasskey/sdk-node';

const wpk = createClient({
  apiUrl: 'https://api.withpasskey.xyz',
  clientId: process.env.WITHPASSKEY_CLIENT_ID!,
  clientSecret: process.env.WITHPASSKEY_SERVER_SECRET! // never ships to the browser
});

// POST /api/exchange →
const tokens = await wpk.exchangeCode({
  code,                        // pkc_… from the callback
  redirectUri: 'https://your.app/callback', // exact match to /authorize
  codeVerifier                 // from consumePending()
});
// → { id_token, assertion, token_type: 'Bearer', expires_in: 120 }

const claims = await wpk.verifyAssertion(tokens.id_token, nonce);
// verifies signature, issuer, audience — and nonce if supplied
// → the session is YOURS: cookie, JWT, however you build it

Assertion claims

ES256 JWT, 120s exp, kid-pinned to /.well-known/jwks.json
claimmeaning
isshttps://api.withpasskey.xyz
audyour client_id (pk_…)
subpairwise subject — stable per (app, user), unlinkable across apps
acrurn:withpasskey:acr:passkey — a passkey ceremony produced this assertion
jtiunique assertion id — replay-detect with it
ridthe auth_request id this assertion completed
nonceyour nonce from /authorize, echoed back — verify it
iat / expissued-at / +120s expiry

Enrolling users

Mint a one-time enrollment ticket server-side, hand the user the hosted link. Registration creates the passkey, links user ↔ app, and returns 10 one-time recovery codes (pkr-…) shown once.

server-side
const { ticket, enrollUrl, expiresInSeconds } = await wpk.mintEnrollTicket({
  userRef: 'your-internal-user-id',  // optional, stored on the ticket
  ttlMinutes: 60 * 24              // default 1440 (24h), max 10080
});
// → send the user enrollUrl:
//   https://id.withpasskey.xyz/enroll?ticket=pkt_…

Recovery

A recovery code re-opens registration for the same user — no email, no reset link. Hosted at https://id.withpasskey.xyz/recover, or POST /v1/recover with a pkr-… code → returns registration options for a new passkey on the existing user.

Multiple origins, one account

Register each verified origin on the application — e.g. french.example.com and spanish.example.com. /authorize accepts any verified origin of the app, and the pairwise sub is identical on all of them — one user, one account, many domains.

Secrets and origins

client_secret never leaves your backend — it is what lets you exchange codes and mint tickets. Redirect URIs must match a verified origin exactly: scheme, host, port, path. There is no password-reset email to fall back on — recovery codes are the only account-recovery path; tell users to store them offline.