# Integrate WithPasskey · 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…

Canonical: https://withpasskey.xyz/docs

Locale: en

*Published 2026-11-17 · updated 2026-11-17*

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.

- [The model](#b-h-model)
- [The sign-in flow](#b-h-flow)
- [Drop-in web component](#b-h-el)
- [Node SDK — backend side](#b-h-sdk)
- [Assertion claims](#b-h-claims)
- [Enrolling users](#b-h-enroll)
- [Recovery](#b-h-rec)
- [Multiple origins, one account](#b-h-dom)

<a id="b-h-model"></a>

## 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.

<a id="b-h-flow"></a>

## 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.

<a id="b-h-el"></a>

## Drop-in web component

```html
<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.

```ts
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
  })
});
```

<a id="b-h-sdk"></a>

## Node SDK — backend side

```ts
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
```

<a id="b-h-claims"></a>

## Assertion 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 |

*ES256 JWT, 120s exp, kid-pinned to /.well-known/jwks.json*

<a id="b-h-enroll"></a>

## 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.

```ts
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_…
```

<a id="b-h-rec"></a>

## 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.

<a id="b-h-dom"></a>

## 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.
