WalletHandlers
The WalletHandlers class is a server-side component that automates the setup of the required API endpoints for a DID Connect flow within an Express.js application. It acts as the bridge between your application's server and the user's DID Wallet.
By using WalletHandlers, you don't have to manually create routes for generating session tokens, checking authentication status, or handling wallet responses. The class takes care of this boilerplate, allowing you to focus on your application logic within specific lifecycle callbacks.
This component works in tandem with the WalletAuthenticator, which handles the creation and signing of the data exchanged during the process.
How It Works#
The primary method of this class is attach(). When you call this method, it registers a set of standardized API endpoints onto your Express app instance. These endpoints follow the DID Connect protocol, enabling communication with a compatible wallet.
This diagram shows how WalletHandlers fits into your application stack:
Initializing WalletHandlers#
First, you need to create an instance of WalletHandlers. The constructor requires your configured authenticator and tokenStorage instances.
const WalletHandlers = require('@did-connect/handler/wallet');
// Assuming 'authenticator' and 'tokenStorage' are already configured
const handlers = new WalletHandlers({
authenticator,
tokenStorage,
});Constructor Parameters#
Parameter | Type | Description |
|---|---|---|
|
| Required. An instance of |
|
| Required. An instance of a token storage class. Responsible for creating and managing session state. |
|
| Optional. A global callback triggered when a wallet connects for any action. Useful for logging or dynamic claims. |
|
| Optional. A function to modify the default endpoint URL paths. See Customizing URLs. |
|
| Optional. An object to customize behavior such as URL prefixes ( |
Attaching Endpoints with attach()#
The core function is attach(), which binds the DID Connect routes to your app for a specific action (e.g., 'login'). You provide callbacks to handle the results of the user interaction.
// In your server setup file (e.g., app.js)
handlers.attach({
app: expressApp,
action: 'login', // This will create endpoints under '/api/did/login'
claims: [{ type: 'profile' }], // Request user's profile
onAuth: (req, res, claims) => {
// User is authenticated!
// 'claims' contains the data returned from the wallet.
// Here you would typically create a user session for your app.
console.log('User logged in:', claims.userDid);
// The library handles sending the success response to the wallet.
},
onComplete: (req, res, session) => {
console.log('Login flow complete for session:', session.token);
},
onDecline: (req, res, session) => {
console.log('User declined login for session:', session.token);
}
});attach() Parameters#
The attach method accepts a configuration object with the following key parameters:
Parameter | Type | Description |
|---|---|---|
|
| Required. The Express.js application instance. |
|
| Required. A unique name for this flow (e.g., 'login', 'claim'). It becomes part of the URL. |
|
| Required. Callback executed after the wallet successfully returns the user's data. This is where you handle the authenticated result. |
|
| An array of claims to request from the user, such as profile info or a verifiable credential. |
|
| Callback executed when a new session token is generated. |
|
| Callback executed when the wallet scans the QR code and requests the challenge. Can be used for Dynamic Claims. |
|
| Callback for when the user explicitly declines the request in their wallet. |
|
| Callback for when the entire process is finished and the session token is removed. |
|
| Callback for when the session token expires before completion. |
|
| A general error handler for the process. |
Generated API Endpoints#
Calling handlers.attach({ action: 'login' }) automatically creates the following routes under the default /api/did/login prefix:
Method | Endpoint | Consumer | Description |
|---|---|---|---|
|
| Web App | Generates a new session token and a DID Connect URL for the QR code. |
|
| Web App | Allows the front-end to poll for the status of the authentication session (e.g., 'pending', 'scanned', 'succeed'). |
|
| Web App | Allows the front-end to manually expire a session token. |
|
| Wallet | The wallet calls this endpoint after scanning the QR code to fetch the authentication request (challenge). |
|
| Wallet | The wallet submits the user's signed response to this endpoint. |
Next Steps#
You now understand how WalletHandlers sets up the server-side infrastructure for DID Connect. To see these endpoints used in a complete tutorial, proceed to the Getting Started guide.
For a detailed list of all methods and parameters, refer to the WalletHandlers API Reference.