Passkeys provide a secure way to authorize actions on Privy server wallets. This guide shows how to integrate your existing passkey implementation as an authorization mechanism for Privy server wallets, combining modern authentication with powerful onchain actions.

Overview

Authorization keys provide a way to ensure that actions taken by your app’s wallets can only be authorized by an explicit user request. When you specify an owner of a resource, all requests to update that resource must be signed with this key. This security measure verifies that each request comes from your authorized passkey owner and helps prevent unauthorized operations.

Setting up passkeys

If you need a passkey implementation set up for your application, we recommend using the simpleWebAuthn SDKs, which provides simple passkey registration and authentication flows.

Creating and registering server wallets with passkey authorization

Follow these steps to create a server wallet and register it with a user’s passkey for authorization.
  1. Retrieve the user’s passkey P-256 PEM-formatted public key and send it to your backend.
  1. From your backend, call the Privy API to create a wallet with that P-256 public key as the owner. You can do this via the Privy SDK (below) or by hitting the Privy API directly.
const passkeyP256PublicKey = 'your-p256-public-key';

const privy = new PrivyClient('your-app-id', 'your-app-secret');

const wallet = await privyClient.walletApi.createWallet({
  owner: {
    publicKey: passkeyP256PublicKey
  }
});
  1. Associate the returned wallet ID with the user on your backend for use in future requests.

Sending transactions with passkey authorization

Below are the steps necessary to create a transaction request, have the user sign it with their passkey using WebAuthn, and submit the signed request to Privy:
  1. Create and format the transaction request payload
Create your transaction and format it into the required request payload structure:
import {canonicalize} from 'canonicalize';
import {startAuthentication} from '@simplewebauthn/browser';

// Your transaction details
const transaction = {
  to: '0x...',
  value: '1000000000000000000', // 1 ETH in wei
  chain_id: 1, // Ethereum mainnet
  data: '0x',
  gas_limit: '21000',
  nonce: 42,
  type: 2
};

// Format the request payload for Privy API
const requestPayload = {
  version: 1,
  method: 'POST',
  url: `https://api.privy.io/v1/wallets/${serverWallet.id}/rpc`,
  body: {
    method: 'eth_signTransaction',
    params: {
      transaction: {
        to: transaction.to,
        value: transaction.value,
        chain_id: transaction.chain_id,
        data: transaction.data,
        gas_limit: transaction.gas_limit,
        nonce: transaction.nonce,
        type: 2
      }
    }
  },
  headers: {
    'privy-app-id': process.env.NEXT_PUBLIC_PRIVY_APP_ID!
  }
};

// Canonicalize the payload for consistent signing
const canonicalPayload = canonicalize(requestPayload) as string;

// Convert to base64url as required by Privy's specification
function base64UrlEncode(str: string) {
  return btoa(str).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
}

const payloadBase64Url = base64UrlEncode(canonicalPayload);
  1. Sign the payload with the user’s passkey
Use the WebAuthn authentication flow to sign the formatted payload:
// Sign the payload using simpleWebAuthn
const authResponse = await startAuthentication({
  optionsJSON: {
    challenge: payloadBase64Url,
    allowCredentials: [], // Empty to discover available credentials
    userVerification: 'preferred',
    rpId: 'yourdomain.com', // Must match the rpID from registration
    timeout: 60000 // 60 seconds
  }
});

// Extract the WebAuthn response components
const signature = authResponse.response.signature;
const authenticatorData = authResponse.response.authenticatorData;
const clientDataJSON = authResponse.response.clientDataJSON;
  1. Format the authorization signature
Create the specially formatted authorization signature that Privy expects:
// Format the authorization signature for Privy
const authorizationSignature = `webauthn:${authenticatorData}:${clientDataJSON}:${signature}`;
  1. Send the transaction to Privy
Send the transaction request with the WebAuthn authorization signature:
// Send the transaction to Privy API
const response = await fetch(`https://api.privy.io/v1/wallets/${serverWallet.id}/rpc`, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'privy-app-id': process.env.NEXT_PUBLIC_PRIVY_APP_ID!,
    'privy-authorization-signature': authorizationSignature,
    Authorization: `Bearer ${accessToken}` // Your app's access token
  },
  body: JSON.stringify({
    method: 'eth_signTransaction',
    params: {
      transaction: {
        to: transaction.to,
        value: transaction.value,
        chain_id: transaction.chain_id,
        data: transaction.data,
        gas_limit: transaction.gas_limit,
        nonce: transaction.nonce,
        type: 2
      }
    }
  })
});

const result = await response.json();
console.log('Transaction result:', result);
That’s it! Your users can now securely authorize transactions on server wallets using their passkeys with WebAuthn standard authentication. 🎉