BSV blockchainBSV blockchain

Authenticate users with their wallet

Mutual authentication lets an API identify each caller by the identity key of the user’s BSV blockchain wallet, so a route knows who sent the request without accounts or passwords. This fits an API that serves a user’s own data or actions. In this guide you build an Express API that reads the identity key behind each request, then a Node client that signs its requests from BSV Desktop. Both run in one project you can adapt to your API.

Before you begin

You need Node.js 22 or newer and a testnet wallet in BSV Desktop. Send a payment from a web app shows how to set one up. The BSV Desktop windows in this guide come from version 3.1.1.

How it works

Mutual authentication runs before a route does. The wallet and the server prove their identity keys to each other, so only a verified caller reaches your code:

BSV Desktop

Signs the request with the user identity key.

Client

Sends the signed request through AuthFetch.

Server

Checks the caller with the middleware and reads the identity key.

Every route can then read the caller as req.auth.identityKey.

Set up the authenticated API

Start with the server that identifies the caller, then add a client that calls it, both in one new project folder.

Protect the API with the auth middleware

Follow these steps in that folder to build the server and read the caller in a route:

Install the packages

Install the packages and the TypeScript runner:

npm install @bsv/auth-express-middleware @bsv/sdk @bsv/wallet-toolbox express
npm install --save-dev tsx typescript @types/express @types/node

The middleware works with @bsv/sdk 2.8.5 or later in the 2.x line, and with 3.x. The code in this guide uses top-level await, so set "type": "module" in your package.json.

Create the server wallet

Create wallet.ts in the project folder:

wallet.ts
import { PrivateKey } from '@bsv/sdk'
import { Setup } from '@bsv/wallet-toolbox'

export async function createServerWallet(rootKeyHex = PrivateKey.fromRandom().toHex()) {
  const identityKey = PrivateKey.fromHex(rootKeyHex).toPublicKey().toString()
  const filePath = `server-${identityKey.slice(0, 8)}.sqlite`
  const env = {
    chain: 'test' as const,
    identityKey,
    identityKey2: identityKey,
    filePath,
    taalApiKey: '',
    devKeys: {},
    mySQLConnection: ''
  }
  const { wallet } = await Setup.createWalletSQLite({ env, rootKeyHex, filePath, databaseName: 'server' })
  return wallet
}

The middleware signs its responses with a wallet that implements WalletInterface, and a bare ProtoWallet does not qualify. The identity key of this wallet is the identity of your server.

Setup reads only chain from env when you pass rootKeyHex, and the other fields are values that the SetupEnv type requires. The file name uses the start of the identity key, so each key gets its own wallet database.

Add the middleware

Next, create server.ts in the same folder:

server.ts
import express from 'express'
import { createAuthMiddleware, type AuthRequest } from '@bsv/auth-express-middleware'
import { createServerWallet } from './wallet.js'

const wallet = await createServerWallet()
const app = express()
app.use(express.json())
app.use(createAuthMiddleware({ wallet }))

Authentication is required by default, so a request without the authentication headers gets a 401 response.

Read the caller in a route

Add the route in server.ts, below the middleware lines:

server.ts
app.get('/private', (req: AuthRequest, res) => {
  res.json({ identityKey: req.auth?.identityKey })
})

app.listen(3000, () => console.log('Server on http://localhost:3000'))

The value of req.auth.identityKey is the identity key of the wallet that signed the request. To also receive the certificatesSigned statements about a user, issued by a third party, like a verifiable credential the caller holds, the middleware accepts certificatesToRequest and onCertificatesReceived, described on the package page on npm.

Call the API with AuthFetch

With the server ready, create the client that signs its requests from BSV Desktop:

Create the client

Create client.ts in the same folder:

client.ts
import { AuthFetch, WalletClient } from '@bsv/sdk'

const wallet = new WalletClient('auto', 'localhost')
const authFetch = new AuthFetch(wallet)

const response = await authFetch.fetch('http://localhost:3000/private')
console.log(await response.json())

The second argument of WalletClient is the originator, the name BSV Desktop shows for your app in its permission windows. BSV Desktop keeps permissions per originator, and a Node script cannot reach the wallet without one.

Start the server

Start the server in one terminal:

npx tsx server.ts

It prints the line below and then stays busy:

Server on http://localhost:3000

Run the client

Run the client in the second terminal, with BSV Desktop open and unlocked:

npx tsx client.ts

The client prints the identity key of the BSV Desktop wallet that signed the request:

{ identityKey: '<identity key of your wallet>' }

BSV Desktop shows the start of this key for each profile under Wallet profiles.

The response also carries the identity key of the server in the x-bsv-auth-identity-key header, so the client can tell which server answered.

By default BSV Desktop answers these calls without asking. With Require permission for signature creation, Require permission for public key revelation and Require permission for identity key revelation turned on in Settings, and the app reloaded, the first call opens two Protocol Access Request windows, for identity key retrieval and auth message signature. Click Grant Access to let the call through, and BSV Desktop remembers the choice for the originator.

Customize and deploy

Once the basic flow works, decide who can call the API and get the server ready for real traffic.

Handle callers without authentication

To serve a route to everyone and still identify the callers who are authenticated, set allowUnauthenticated:

server.ts
app.use(createAuthMiddleware({ wallet, allowUnauthenticated: true }))

A request from AuthFetch still reaches the route with the real identity key, and any other request arrives with the identity key unknown. Treat unknown as “not authenticated” and never as permission to do anything.

Keep the server identity stable

To keep one server identity across restarts, create the key once and pass it to createServerWallet:

Generate the key

node -e "import('@bsv/sdk').then(({ PrivateKey }) => console.log(PrivateKey.fromRandom().toHex()))"

The key is the identity of your server, and anyone who holds it can run a server with your identity. Keep it private, in a secret store, and never paste it into code or commit it.

Pass the key to the wallet

Save the key as SERVER_ROOT_KEY in a .env file that is in your .gitignore, and read it in server.ts:

server.ts
const wallet = await createServerWallet(process.env.SERVER_ROOT_KEY)

Start the server with npx tsx --env-file=.env server.ts.

Without a key, the server gets a new random one, and so a new identity, at every start. BSV Desktop stores its auth message signature permission per server identity key.

Prepare the API for production

Before the API serves real users, check these points:

  • Share the session state across instances. The default session manager lives in the memory of one process, so a service with several instances needs a shared sessionManager.
  • Review transportLimits. The defaults are a 30 second request timeout, 1,000 pending requests per process and 8 MiB for a signed response, and a request over a limit is rejected with 413 or 503. Do not set maxPendingRequests too low, because each authenticated request can hold more than one pending slot.
  • Move off testnet by following Move your app to mainnet.

To adopt this in a real API, add createAuthMiddleware to the routes you want to protect and keep the server root key in your secret store.

Troubleshooting

Request rejected without the authentication headers #

The request reached a protected route without the authentication headers, and the middleware answers Mutual-authentication failed!. Call the route with AuthFetch, or set allowUnauthenticated on the middleware if the route must accept anonymous callers.

Client cannot reach the wallet #

The script reached no wallet and throws No wallet available over any communication substrate. A Node script cannot connect to BSV Desktop without an originator, so pass one as the second argument of WalletClient, as in client.ts, and keep BSV Desktop open and unlocked.

Server wallet does not implement WalletInterface #

The middleware and AuthFetch take a WalletInterface. A ProtoWallet does not implement it and fails with Type 'ProtoWallet' is missing the following properties from type 'WalletInterface'. Pass a wallet like the one createServerWallet returns.

Script runs the files as CommonJS #

The runner tsx runs the files as CommonJS. The script stops with Top-level await is currently not supported with the "cjs" output format. Set "type": "module" in your package.json.

Next steps

With the authenticated API running, continue with: