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
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
- Browser →
GET /authorize?client_id&redirect_uri&response_type=code&code_challenge&code_challenge_method=S256(state + nonce optional) - The broker validates client status + verified redirect origin, then hosts the passkey ceremony
- On success the browser returns to your
redirect_uriwith a one-timecode(pkc_…, 60s) and yourstate - Your backend exchanges the code at
POST /v1/tokenwithclient_secret+ the PKCEcode_verifier - 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
<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.
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
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 itAssertion claims
| claim | meaning |
|---|---|
| iss | https://api.withpasskey.xyz |
| aud | your client_id (pk_…) |
| sub | pairwise subject — stable per (app, user), unlinkable across apps |
| acr | urn:withpasskey:acr:passkey — a passkey ceremony produced this assertion |
| jti | unique assertion id — replay-detect with it |
| rid | the auth_request id this assertion completed |
| nonce | your nonce from /authorize, echoed back — verify it |
| iat / exp | issued-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.
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.