# L3 passkeys

> Add a passkey step on top of L2 so that a WebAuthn credential signs a challenge bound to the documents and the session before the final act.

Source: https://esigncomply.com/docs/guides/l3-passkeys

L3 is L2 plus a passkey. After Esign Comply has verified control of the signer's email address or phone number, the signer's device signs a one-use challenge with a WebAuthn credential. The challenge is derived from the session, the signer and the exact document versions, so the credential's response is tied to this signing act and no other.

L3 is available on the Unlimited plan and above, in test mode as well as live. A session for an L3 profile on another plan returns [`plan_feature_unavailable`](https://esigncomply.com/docs/api/errors.md#plan_feature_unavailable).

## What L3 records, and what it does not

Esign Comply records that a registered credential, protected by the device's own user verification (a fingerprint, a face, or a PIN), answered a challenge bound to the frozen pre-signature payload. It stores the credential ID, a hash of the payload the challenge was bound to, whether the credential is single-device or multi-device, and whether it is backed up.

L3 does not establish legal identity, authority to sign, or sole control of the credential. Passkeys can sync across a person's devices and can be recovered through the platform account. The record says so. An L3 record is still a simple electronic signature: the passkey raises the assurance level, and `signature_level` stays `simple`.

## Set up

Create a profile with `assurance_level: "L3"`. Use `method: "passkey"` to record the final act as a passkey signature combined with a typed name, or `method: "typed"` to keep the typed name as the method and add the passkey as verification.

```bash
curl https://esigncomply.com/v1/profiles \
  -H "Authorization: Bearer $ESIGNCOMPLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Master services agreement",
    "jurisdictions": ["US-FED"],
    "document_type": "contract",
    "method": "passkey",
    "assurance_level": "L3"
  }'
```

`method: "passkey"` is accepted only with `assurance_level: "L3"`.

A session for this profile lists both verification steps:

```json
[
  "client.attached",
  "document.presented:dv_3kT9",
  "notice.captured",
  "identity.verified",
  "identity.verified:passkey",
  "intent.captured",
  "signature.applied"
]
```

`identity.verified` is the L2 channel verification. `identity.verified:passkey` is the passkey step. Both must be recorded before the final act, in that order.

## With the browser SDK

Run the L2 step first, as in [L2 verification](https://esigncomply.com/docs/guides/l2-verification.md). Then call `ceremony.verify.passkey()` from a button the signer presses. Browsers show the passkey prompt only in response to a user action. The method takes no arguments and resolves with `{ id, status, attemptsRemaining }`, where `status` is `"confirmed"`, `"failed"` or `"registered"`.

```tsx
"use client";

import { useState } from "react";
import type { Ceremony, EsignComplyError } from "@esigncomply/browser";

export function PasskeyStep({ ceremony, onVerified }: { ceremony: Ceremony; onVerified: () => void }) {
  const [busy, setBusy] = useState(false);
  const [message, setMessage] = useState<string | null>(null);

  async function usePasskey() {
    setBusy(true);
    setMessage(null);
    try {
      const result = await ceremony.verify.passkey();
      if (result.status === "confirmed") onVerified();
      // "failed": the API could not verify the response. "registered": a passkey was created but not used yet.
      else setMessage("The passkey could not be checked. Please try again.");
    } catch (err) {
      const error = err as EsignComplyError;
      // verification_failed: no passkey support in this browser, or the prompt was dismissed.
      // step_out_of_order: the email or phone verification has not been confirmed yet.
      // plan_feature_unavailable: the plan does not include L3.
      setMessage(error.message);
    } finally {
      setBusy(false);
    }
  }

  return (
    <section aria-label="Confirm with a passkey">
      <p>Confirm this signing with a passkey on this device. If you do not have one for this site yet, your device will offer to create it.</p>
      <button type="button" onClick={usePasskey} disabled={busy}>
        Confirm with passkey
      </button>
      {message ? <p role="alert">{message}</p> : null}
    </section>
  );
}
```

One call covers both cases:

- **The signer already has a passkey for your domain.** The browser asks them to use it. The call resolves with `status: "confirmed"`.
- **The signer has none.** The browser first asks them to create a passkey. The SDK then starts a second verification at once and the browser asks them to use the new passkey. The signer sees two prompts. The call resolves with `status: "confirmed"` after the second.

The call resolves with `status: "failed"` when the API could not verify what the browser returned. Each call starts a new verification, so call `ceremony.verify.passkey()` again to retry. The SDK registers at most once per call: if the API asks for a registration twice in a row, the call resolves with `status: "registered"` and the step is still outstanding.

When the step is recorded, the SDK emits `stepRecorded` for `identity.verified` and `ceremony.remainingSteps()` no longer lists `identity.verified:passkey`. Keep the signing button disabled until only `"signature.applied"` is left, then let the signer type their name and press the button. See the NDA example in the [Next.js guide](https://esigncomply.com/docs/guides/nextjs.md) for the assent container.

If the browser has no passkey support, or the signer dismisses the prompt, the call rejects with an `EsignComplyError` whose `code` is `verification_failed`, with `status` 0 and rule `CR-17`. The verification that was started is left unconfirmed and no attempt is counted. Let the signer try again. An L3 session cannot be completed without the passkey step. If some of your signers cannot use passkeys, offer them a flow on an L2 profile instead, as a product decision you make and document.

With a profile whose `method` is `passkey`, `ceremony.complete()` sends `passkey` as the signature method when `verify.passkey()` resolved with `confirmed` on the same ceremony object. After a page reload the passkey step stays recorded, and the new ceremony object sends the method the assent controls give, for example `typed`.

## How the two phases work

The SDK drives two API calls per phase with the session client token: it starts a verification, runs the browser prompt, and confirms the verification with the browser's response. You need this section only to understand the record or to debug.

Between the two calls the SDK converts the options for the browser. It decodes the base64url values (`challenge`, `user.id` and the `id` of each entry in `allowCredentials` and `excludeCredentials`) to bytes. It calls `navigator.credentials.create()` when the options carry a `user`, and `navigator.credentials.get()` otherwise. It sends the result back as JSON with `id`, `rawId`, `type`, `authenticatorAttachment`, `clientExtensionResults` and `response`, with every binary field encoded as base64url.

### Register

When the signer has no stored credential for this relying party, `POST /v1/sessions/{id}/verifications` answers with `phase: "register"` and WebAuthn creation options.

```http
POST /v1/sessions/ses_5nWq/verifications
Authorization: Bearer esc_ct_...
Content-Type: application/json

{ "method": "passkey" }
```

`201 Created`

```json
{
  "object": "verification",
  "id": "ver_2bQd",
  "method": "passkey",
  "status": "pending",
  "phase": "register",
  "options": {
    "challenge": "c29tZS1yYW5k...",
    "rp": { "name": "Example, Inc.", "id": "example.com" },
    "user": { "id": "c2duXzdLcDI", "name": "dana@example.org", "displayName": "" },
    "pubKeyCredParams": [{ "alg": -8, "type": "public-key" }, { "alg": -7, "type": "public-key" }, { "alg": -257, "type": "public-key" }],
    "timeout": 60000,
    "attestation": "none",
    "excludeCredentials": [],
    "authenticatorSelection": { "residentKey": "preferred", "userVerification": "required" }
  },
  "expires_at": "2026-11-21T15:13:01.000Z",
  "attempts_remaining": 5
}
```

The options are WebAuthn creation options and can carry further standard members. The browser creates the credential and the SDK sends the result as `attestation`:

```http
POST /v1/sessions/ses_5nWq/verifications/ver_2bQd/confirm
Authorization: Bearer esc_ct_...
Content-Type: application/json

{ "attestation": { "id": "...", "rawId": "...", "type": "public-key", "authenticatorAttachment": "platform", "clientExtensionResults": {}, "response": { "clientDataJSON": "...", "attestationObject": "...", "transports": ["internal"] } } }
```

```json
{
  "object": "verification",
  "id": "ver_2bQd",
  "method": "passkey",
  "status": "registered",
  "next": "start_passkey_authentication",
  "attempts_remaining": 5
}
```

`200 OK`. `registered` means the public key is on file for this signer. It does not record the passkey step. The caller starts a passkey verification again to sign in with the new credential. `ceremony.verify.passkey()` does this for you.

### Authenticate

With a credential on file, the same start call answers with `phase: "authenticate"` and WebAuthn request options. The `challenge` is not random alone: it is the SHA-256 hash of a canonical object that names the session, the signer's external ID, each document version with its content hash, the profile and its version, the purpose, and a one-use nonce.

```json
{
  "object": "verification",
  "id": "ver_9Lm3",
  "method": "passkey",
  "status": "pending",
  "phase": "authenticate",
  "options": {
    "challenge": "0u5S1fVQ3m0v...",
    "rpId": "example.com",
    "allowCredentials": [{ "id": "Zm9vYmFyY3JlZGVudGlhbA", "type": "public-key" }],
    "timeout": 60000,
    "userVerification": "required"
  },
  "expires_at": "2026-11-21T15:14:10.000Z",
  "attempts_remaining": 5
}
```

The SDK sends the signed response as `assertion`:

```http
POST /v1/sessions/ses_5nWq/verifications/ver_9Lm3/confirm
Authorization: Bearer esc_ct_...
Content-Type: application/json

{ "assertion": { "id": "Zm9vYmFyY3JlZGVudGlhbA", "rawId": "...", "type": "public-key", "authenticatorAttachment": "platform", "clientExtensionResults": {}, "response": { "clientDataJSON": "...", "authenticatorData": "...", "signature": "...", "userHandle": "..." } } }
```

```json
{
  "object": "verification",
  "id": "ver_9Lm3",
  "status": "confirmed",
  "attempts_remaining": 5,
  "remaining_steps": ["intent.captured", "signature.applied"]
}
```

`200 OK`. Esign Comply looks up the stored credential by the `id` of the assertion, verifies the signature against its public key, with the challenge, origin and relying party it expects, and requires user verification. It then records an `identity.verified` event for the step `identity.verified:passkey` and returns the steps still outstanding. A `register` confirmation without `attestation`, or an `authenticate` confirmation without `assertion`, returns `400` [`invalid_request`](https://esigncomply.com/docs/api/errors.md#invalid_request).

## What the challenge is bound to

The challenge covers the pre-signature payload, fixed before the signer acts:

| Bound | Not bound |
|---|---|
| Session ID | The typed name |
| Signer external ID | The final record, which contains the assertion itself |
| Each document `version_id` and `content_hash` | Later annotations |
| Profile ID and version | |
| `context.purpose` | |
| A one-use nonce | |

The event data keeps a hash of that object as `challenge_binding`, with `bound_to: "pre_signature_payload"`. A response made for one session cannot be replayed for another session, another signer or another document version.

## Relying party and origin

The ceremony runs on your own page, so the passkey belongs to your domain, not to Esign Comply.

- In live mode the relying party ID is your registered domain, for example `example.com`. A passkey created on `app.example.com` works on every subdomain.
- In test mode it is the host of the page, for example `localhost`.
- The origin of the request must be the page that ran the prompt. The API checks it against the browser's `Origin` header.

A credential registered for one relying party is not offered for another. A signer who registered on `localhost` in test mode registers again on your live domain. On a later L3 ceremony for the same `signer.external_id` on the same domain, the stored credential is reused and only the authenticate phase runs.

## Order and errors

| Situation | Response |
|---|---|
| Passkey step started before the email or phone verification is confirmed | `409` [`step_out_of_order`](https://esigncomply.com/docs/api/errors.md#step_out_of_order) with `missing_steps: ["identity.verified"]` |
| Plan below Unlimited | `403` [`plan_feature_unavailable`](https://esigncomply.com/docs/api/errors.md#plan_feature_unavailable) |
| Response does not verify (unknown credential, wrong origin, no user verification) | `200` with `status: "failed"` and a lower `attempts_remaining` |
| Fifth failed attempt on one verification | `422` [`verification_failed`](https://esigncomply.com/docs/api/errors.md#verification_failed). The session is cancelled. |
| Options older than 10 minutes | `422` `verification_failed`. Start again. |
| No passkey support in the browser, or the prompt was dismissed | The browser SDK rejects with `verification_failed` and `status` 0. No request is sent to confirm. |
| Final act without the passkey step | `422` [`steps_incomplete`](https://esigncomply.com/docs/api/errors.md#steps_incomplete) with `identity.verified:passkey` in `missing_steps` |

The conformance rule is [CR-17](https://esigncomply.com/docs/conformance.md#cr-17).

## What ends up in the record

```json
{
  "assurance_level": "L3",
  "signature_level": "simple",
  "signer": {
    "external_id": "user_7c1d",
    "verified_email": "dana@example.org",
    "typed_name": "Dana Whitfield",
    "verification": [
      { "method": "email_otp", "destination": "d***@example.org", "at": "2026-11-21T15:04:11.902Z", "attempts": 1 },
      { "method": "passkey", "destination": "passkey", "at": "2026-11-21T15:04:39.417Z", "attempts": 1 }
    ]
  }
}
```

The `identity.verified` event for the passkey is tagged `observed` and carries these fields, among others:

```json
{
  "method": "passkey",
  "credential_id": "Zm9vYmFyY3JlZGVudGlhbA",
  "challenge_binding": "sha256:7ac1...",
  "bound_to": "pre_signature_payload",
  "device_type": "multiDevice",
  "backed_up": true,
  "note": "A synced or recovered credential does not establish sole control."
}
```

The evidence report states the method and the assurance level. It does not describe the signer as identified.

## Checklist

- The profile is `L3` and the domain's plan is Unlimited or above.
- The page runs the L2 verification first, then the passkey step, then the assent container.
- `ceremony.verify.passkey()` is called from a click handler.
- The typed-name field starts empty and the signing button stays disabled until only `"signature.applied"` remains.
- Your [server confirmation](https://esigncomply.com/docs/guides/server-confirmation.md) does not change: it checks status, `livemode`, signer and versions. You may also require `assurance_level === "L3"` for the flows that need it.
