Using passkeys with server wallets

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 WebAuthn standard, which provides phishing-resistant, passwordless authentication.

Sample passkey registration flow (if needed)

If you have not already done so, install the dependencies necessary for a simple passkey integration. sh npm install @simplewebauthn/server @simplewebauthn/browser

// Server-side registration endpoint
app.post('/api/register-passkey/begin', async (req, res) => {
  const userId = req.body.userId;

  // Generate registration options
  const options = await generateRegistrationOptions({
    rpName: 'Your App Name',
    rpID: 'yourdomain.com',
    userID: userId
    // Additional options...
  });

  // Store options temporarily
  await storeRegistrationOptions(userId, options);

  return res.json(options);
});

// Client-side registration
async function registerPasskey() {
  // Get registration options from your server
  const options = await fetchRegistrationOptions();

  // Start the registration process in the browser
  const attestation = await startRegistration(options);

  // Send the response to your server for verification
  const verification = await verifyRegistration(attestation);

  return verification;
}

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.

Retrieve the user’s passkey P-256 public key and send it to your backend.
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
  }
});

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, and submit the signed request to Privy:

On your client, create you desired transaction request body.
Format the request body in preparation for signing. You can do this manually or using the Privy SDK (below).

import {formatRequestForAuthorizationSignature} from '@privy-io/server-auth/wallet-api';

const input: WalletApiRequestSignatureInput = ...;
const serializedPayload = formatRequestForAuthorizationSignature(input);

Sign the formatted transaction request with the user’s passkey.
Send the signature and transaction request to your backend.
Send the transaction request with the signature to the Privy API.
- Set the privy-authorization-signature header to the signature you created in step 3.
- Set the request body as the transaction request you created in step 1.

That’s it! Whenever a user registers a passkey for your app, they will then have access to a provisioned server wallet for secure and flexible transaction signing and sending. 🎉

Recipes

​Overview

​Setting up passkeys

​Creating and registering server wallets with passkey authorization

​Sending transactions with passkey authorization

Overview

Setting up passkeys

Creating and registering server wallets with passkey authorization

Sending transactions with passkey authorization