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.
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.
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.
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:
[
"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. 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".
"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 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.
POST /v1/sessions/ses_5nWq/verifications
Authorization: Bearer esc_ct_...
Content-Type: application/json
{ "method": "passkey" }
201 Created
{
"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:
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"] } } }
{
"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.
{
"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:
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": "..." } } }
{
"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.
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 onapp.example.comworks 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
Originheader.
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 with missing_steps: ["identity.verified"] |
| Plan below Unlimited | 403 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. 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 with identity.verified:passkey in missing_steps |
The conformance rule is CR-17.
What ends up in the record
{
"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:
{
"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
L3and 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 does not change: it checks status,
livemode, signer and versions. You may also requireassurance_level === "L3"for the flows that need it.