Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/tkhq/sdk/llms.txt

Use this file to discover all available pages before exploring further.

@turnkey/webauthn-stamper stamps Turnkey API requests using a WebAuthn credential (passkey). When a request is about to be sent, the stamper calls the browser’s WebAuthn API to prompt the user for a passkey assertion. The resulting signature is attached to the request as the X-Stamp-Webauthn header. This is the recommended stamper for browser-based applications where you want users to authenticate with their own passkey rather than a server-controlled API key.
Passkeys created on iOS, Android, and modern desktop browsers are fully supported. Cross-device passkey sync via iCloud Keychain, Google Password Manager, and 1Password is also supported wherever the browser exposes it through the WebAuthn API.

​
Installation

npm install @turnkey/webauthn-stamper @turnkey/http

​
Usage

import { WebauthnStamper } from "@turnkey/webauthn-stamper";
import { TurnkeyClient } from "@turnkey/http";

const stamper = new WebauthnStamper({
  rpId: "example.com",
});

// HTTP client that signs with a passkey
const client = new TurnkeyClient(
  { baseUrl: "https://api.turnkey.com" },
  stamper,
);
When you call any TurnkeyClient method, the browser’s WebAuthn dialog appears and the user approves the request with their passkey: 
const whoami = await client.getWhoami({
  organizationId: "your-organization-id",
});

​
WebauthnStamper constructor

​
rpId
string
required
The Relying Party ID for your origin. For https://www.example.com the RPID is typically example.com. For local development use localhost.
​
timeout
number
default:"300000"
How long (in milliseconds) the browser waits for the user to respond to the passkey prompt before the assertion times out. Defaults to 5 minutes.
​
userVerification
UserVerificationRequirement
default:"preferred"
The user verification requirement passed to the WebAuthn API. Accepts "required", "preferred", or "discouraged". Defaults to "preferred".
​
allowCredentials
PublicKeyCredentialDescriptor[]
default:"[]"
An optional list of credential descriptors to pass to navigator.credentials.get. When empty the browser presents all available passkeys for the RPID. Pass specific credential IDs to constrain which passkey the user is prompted for.

​
How passkey signing works

1

Challenge derivation

The stamper SHA-256 hashes the serialized request payload and encodes it as a UTF-8 byte array. This becomes the WebAuthn challenge.
2

WebAuthn assertion

The stamper calls navigator.credentials.get with the challenge. The browser prompts the user to authenticate with their passkey (biometric, PIN, or security key).
3

Stamp construction

The resulting assertion — authenticatorData, clientDataJSON, credentialId, and signature — is serialized to JSON and attached as the X-Stamp-Webauthn header value.
4

Server verification

Turnkey’s backend verifies the assertion against the WebAuthn credential registered for the user, then processes the request.

​
Local development

Set rpId: "localhost" when running your application locally. WebAuthn requires a secure context (https:// or localhost), so passkeys will not work on plain HTTP origins other than localhost. 
const stamper = new WebauthnStamper({
  rpId: "localhost",
});

Build docs developers (and LLMs) love

Get started for freeTalk to us