Skip to main content
Dakota signers can be WebAuthn credentials (passkeys, platform authenticators, or roaming keys like a YubiKey) in addition to raw ES256 keys. A WebAuthn signer endorses an intent by producing a standard WebAuthn assertion — the same object a browser returns from navigator.credentials.get() — rather than a bare ECDSA signature over the intent hash. This page is the reference for the WebAuthn path. If you sign with raw ES256 keys, read Wallet Transaction Signing instead. For the conceptual model, intent catalogue, and signer-group / policy lifecycles (which are identical for both signer types), read Signing & Endorsed Requests.
Why WebAuthn is different. An authenticator never signs an arbitrary hash. It signs authenticatorData ‖ SHA-256(clientDataJSON), and the intent reaches the signature only as the challenge embedded inside clientDataJSON. The verifier therefore needs the whole assertion bundle (authenticatorData, clientDataJSON, signature) — not a DER signature. Everything below exists to thread the intent through that bundle correctly.

The model at a glance

A WebAuthn integration has two phases:
  1. Register — create a WebAuthn credential, extract its COSE public key, and register it as a key_type: WEBAUTHN signer.
  2. Sign — build an intent (a transaction, or a governance change such as adding a member to a signer group), JCS-canonicalize it, use those exact bytes as the WebAuthn challenge, produce an assertion, and submit it.
Once a WebAuthn signer is in a signer group attached to a wallet, it participates in approval thresholds and governance quorums exactly like an ES256 signer, and the two kinds of signature can be mixed in one request. The signer-group and policy mechanics in Signing & Endorsed Requests apply unchanged. Section 3 below works through a member addition signed with a passkey.
Supported algorithms. A WEBAUTHN signer’s COSE key must be ES256 (EC2 / P-256, COSE alg -7) or RS256 (RSA, 2048-bit minimum, COSE alg -257). Other algorithms and curves — including ES384/ES512, Ed25519, and secp256k1 — are rejected at verification time. Virtually all passkeys are ES256, so request [-7, -257] and you will get an ES256 credential.

1. Register a WEBAUTHN signer

1a. Create the credential (browser)

Run a normal WebAuthn registration ceremony. The relying-party options come from your own server; the only Dakota-specific constraint is pubKeyCredParams (i.e. supportedAlgorithmIDs) limited to ES256 / RS256.

1b. Extract the COSE public key (server)

The public key Dakota stores is the raw COSE key (CBOR) embedded in the attestation object — not a PKIX/SPKI blob. The simplest way to get it is to verify the registration with @simplewebauthn/server and read the credential public key it returns:
If you are not using @simplewebauthn/server, the COSE key is the credentialPublicKey field of attestedCredentialData inside the authData of the attestationObject. Decode the attestation CBOR with any CBOR library and walk the standard authenticator-data layout to extract it. The bytes you register are exactly that COSE key, base64-encoded.

1c. Register the signer

Save both the returned signer id (for building signer groups) and the credential.id from step 1a (for signing). Add the signer to a signer group and attach that group to a wallet exactly as you would for an ES256 signer — see the Signer Group Lifecycle.
public_key for a WEBAUTHN signer is the raw CBOR COSE key, base64-encoded. This is a different encoding from key_type: ES256, which expects an X.509 SubjectPublicKeyInfo (PKIX) DER/PEM blob. Sending a PKIX key for a WebAuthn signer (or vice-versa) fails verification later, not at registration.

2. Sign and submit a transaction

The intent and operation schema are identical to the ECDSA flow — only the signing step changes.

2a. Build and canonicalize the intent

2b. The challenge — the one thing that trips integrators up

The challenge is the raw bytes of the RFC 8785 (JCS) canonical intent JSON — not SHA-256(intent), and not any other digest. Do not hash the intent before using it as the challenge. The verifier re-derives the hash itself.
What the verifier does, step by step:
Because the verifier re-canonicalizes whatever it decodes from the challenge, minor formatting differences (key order, trailing decimal zeros, empty strings) are tolerated. Signing the output of your JCS library directly is the safest approach.
context_digest participates automatically. It is an optional field on SendTransactionIntent; because it lives inside the intent object, it is part of the canonical JSON the challenge commits to — no separate handling. The hash is a single SHA-256, not a double hash.

2c. Produce the assertion (browser)

2d. Submit the endorsed request

The request body is the endorsed request — intent and signatures at the top level. There is no wrapper object.
The intent you submit must be the same object you canonicalized and signed — the verifier independently canonicalizes it and compares its hash against the challenge. The signatures array holds one entry per endorsing signer, each from a different member of the group; for a transaction, include as many as the threshold rules in the wallet’s policies require (approval_threshold, or amount_threshold for an amount at or above its minimum).

End-to-end


3. Sign a signer group change with a passkey

We plan to make governance enforcement the default for all clients. Today it is off unless Dakota turns it on for your team, so build and test your integration as if it is on. In practice: collect signatures from signer group members for signer group, policy and wallet changes; manage API keys and users from a signed-in session, not with an API key; give your servers Operate keys that pass along those signed changes; and handle insufficient_endorsements and retry 503 responses, such as check_unavailable.
Adding or removing a member, or changing a group’s governance, is signed by the group’s governance. The passkey signs exactly as in section 2, with two differences:
  • The request body is not an endorsed request. You send the endpoint’s own fields plus signatures and signer_group_version, and Dakota builds the intent from the path, the body and the X-Idempotency-Key header. Your challenge must be the canonical bytes of that same intent.
  • The intent’s idempotency_key is the X-Idempotency-Key header, verbatim. Use a lowercase UUID (crypto.randomUUID() returns one); an uppercase key is refused with 400.
This example adds a new signer, already registered with POST /signers, to a group governed by its own members. The approving passkey belongs to a current member: a key cannot approve its own addition.

3a. Read the group’s version and quorum

version goes into the intent. effective_governance_threshold is how many distinct members must sign: collect that many assertions (or ES256 signatures) over the same intent.

3b. Build the intent and its canonical bytes

canonicalize sorts the keys, so the challenge decodes to exactly this (one line, no spaces):
The challenge is the raw canonical JSON bytes above, not their SHA-256 hash. Dakota decodes the challenge, re-canonicalizes it, and compares it with the intent it builds from your request.

3c. Get the assertion with user verification

Use the signIntent function from 2c, passing 'required' as its third argument so the authenticator only signs after the member’s biometric or PIN check:
A governance change hands control of the wallet to new keys, so require user verification in every governance ceremony. A passkey that signs without it lets anyone holding the unlocked device approve the change.

3d. Submit with the version and the same key

  • X-Idempotency-Key is the idempotency_key you signed, character for character.
  • signer_group_version is the version you signed.
  • member_key is the single entry of new_member_keys.
The response is the updated group, with version now 4. Sending the same request again with the same key within 24 hours returns that response and changes nothing. A signature over version 3 can no longer be used once the version moves on: 409 stale_signer_group_version means read the group again and sign again.

End-to-end

Removing a member

A removal works the same way, with the remove_signers_from_group intent on POST /signer-groups/{signer_group_id}/signer-removals:
A removal that would leave the group without enough members who can sign to meet its thresholds is refused with 422 below_threshold. Every intent’s exact fields are in the Intent Types Reference, and every refusal in Errors.

What goes in signatures[]

Each entry is the WebAuthn assertion serialized as JSON, then base64-encoded — there is no CBOR, no custom concatenation, and no proprietary envelope:
The decoded JSON:
JSON field order is irrelevant. The fields inside response must be base64url; the outer signatures[] string itself may be standard base64 or base64url, padded or not — the decoder accepts all four.

Checks on every assertion

Dakota always checks two things in a passkey signature, besides the challenge and the signature itself. Either failure refuses the whole request with 400, problem type validation-error, and a reason (equal to code) that names the check: Every browser ceremony through navigator.credentials.get() meets both. User verification (the UV flag) is not required today, but request it with userVerification: "required", as in 3c: checks of UV, rpId and origin are planned (see below).

rpId and origin

Today, Dakota does not re-validate rpId or origin server-side. The verifier extracts authenticatorData, clientDataJSON, and signature, checks the challenge binding, the clientDataJSON.type and the user-present flag (see Checks on every assertion), and verifies the signature against the registered COSE key. The rpId and origin are cryptographically bound into the signature but are not compared against an expected value. You still need a valid, stable rpId configured in your relying party to complete the browser ceremony in the first place — use your real domain (and keep it consistent between registration and signing). clientDataJSON.type will be "webauthn.get" naturally.
Server-side checks of user verification, rpId and origin are planned. When they apply, a failing assertion will be refused with 400 and a reason naming the check (webauthn_user_not_verified, webauthn_rp_mismatch or webauthn_origin_mismatch). Request user verification, use your real domain as rpId and keep it stable, so your signatures keep verifying when those checks arrive.

Troubleshooting

Multi-signer approvals. When a wallet’s policy requires more than one approval, collect one signatures[] entry per signer (each a base64url assertion JSON) and submit them together. WebAuthn and ES256 signatures can be mixed in the same signatures array.