Advanced Topics
Once you're comfortable with the basics of DID Connect, you might encounter scenarios that require more fine-grained control or integration with complex existing systems. This section covers advanced usage patterns that give you the flexibility to handle these challenges.
Each topic below provides an overview of a powerful feature. Follow the links for detailed guides and code examples.
Dynamic Claims#
In some cases, the information you need to request from a user depends on who they are or other context discovered after they've initiated a connection. Instead of defining a static list of claims, you can generate them dynamically.
The onConnect callback is the key to this feature. It runs after the user has successfully connected with their wallet (the authPrincipal step) but before subsequent claims are requested. This allows you to inspect the user's DID or other session data and decide which claims to ask for next.
For example, you could check if a user belongs to a specific organization and only then request a verifiableCredential to prove their membership.
Learn how to implement Dynamic Claims
Customizing URLs#
DID Connect is often deployed behind reverse proxies, load balancers, or within applications where API routes are nested. The library is designed to automatically detect the correct public-facing URL for the wallet to communicate with, but you can also override this behavior for full control.
The pathTransformer function allows you to modify the endpoint path before it's encoded in the QR code, and various HTTP headers (like X-Forwarded-Proto and X-Forwarded-Host) are used to construct the correct baseUrl. This ensures that even in complex network architectures, the wallet can always reach your server's DID Connect endpoints.
Event Handling#
The DID Connect session lifecycle—from creation to completion—emits a series of events. By listening to these events, you can build real-time experiences, monitor session status, or trigger custom server-side logic.
The WalletHandlers class is an EventEmitter. You can listen for events like created, updated, and deleted to track the state of authentication tokens. This is useful for things like updating a user's web UI via WebSockets when they scan a QR code or complete a login.
Learn how to use Event Handling
After mastering these topics, you'll be equipped to handle a wide range of integration challenges. For a complete list of all available options and methods, consult the API Reference.