The authPrincipal claim is the cornerstone of any DID Connect session. It is the most fundamental and commonly used claim, designed to ask the user to connect their wallet and select a Decentralized Identifier (DID) to interact with your application. This initial step establishes a secure session and provides the application with the user's primary DID, upon which all subsequent interactions are built.
Think of it as the "Log in with Wallet" button. It doesn't ask for specific personal data, but simply for the user to identify themselves by choosing an account.
When to Use
You should use the authPrincipal claim as the first step in almost any workflow that requires user interaction, including:
- User Login: The most basic use case, allowing users to sign in to your application.
- Session Initiation: Starting a multi-step process where you'll later request more specific information or actions (e.g., signing a transaction or presenting a credential).
- Establishing Context: When you need to know the user's DID to personalize the user experience or check for existing data associated with that DID.
Parameters
The authPrincipal claim can be configured with the following parameters to tailor the request to your needs.
| Parameter | Type | Description |
|---|---|---|
description | string | Required. A message displayed to the user in their wallet, explaining why they are being asked to connect. Defaults to: "Please continue with your account". |
target | string | Optional. A specific DID you suggest the wallet should use. The wallet may ignore this suggestion if the user does not own the DID or chooses another. |
supervised | boolean | Optional. If set to true, it indicates a delegated connection scenario where the wallet might be acting on behalf of another DID. Defaults to false. |
targetType | object | Optional. An object specifying the desired properties of the DID to be selected. This is useful for requesting a DID with specific cryptographic characteristics. |
Target Type Fields
The targetType object can contain the following fields to filter the DIDs presented to the user:
| Field | Type | Description |
|---|---|---|
key | string | The desired key type. Valid values: "ed25519", "secp256k1", "ethereum". Defaults to "ed25519". |
hash | string | The desired hash function. Valid values: "sha3", "keccak", "sha2". Defaults to "sha3". |
role | string | The desired role type of the wallet account. Valid values include "account", "node", "application", "smart_contract", etc. Defaults to "account". |
encoding | string | The desired encoding format. Valid values: "base58", "base16". Defaults to "base58". |
Example Usage
Here's how you would request a user to connect with a standard account. This is typically done within the claims array of your DID Connect configuration.
Requesting a Basic Connection
const claims = {
authPrincipal: {
description: 'Sign in to our awesome app',
},
};
// This claims object would be used by your WalletAuthenticator instance
// when generating the QR code for the user to scan.Example: Requesting a Specific Type of DID
If your application needs to interact with a specific blockchain or requires a certain key type, you can use targetType.
Requesting an Ethereum-compatible DID
const claims = {
authPrincipal: {
description: 'Connect your Ethereum-compatible account',
targetType: {
key: 'ethereum',
role: 'account',
},
},
};Wallet Response
After the user scans the QR code and approves the request in their wallet, your application's onConnect and onAuth handlers will be triggered. The onAuth callback will receive a session object containing the user's selected DID and public key.
Example onAuth Callback
const handlers = new WalletHandlers({
// ...other handlers
onAuth: async (session) => {
console.log('User connected!', session);
// The session object contains:
// session.userDid - e.g., 'z1...' (the user's address)
// session.userPk - The user's public key in base58
// You can now create a user session in your database
// or proceed to the next step in your workflow.
},
});Next Steps
Once a session is established with the authPrincipal claim, you can proceed to request more detailed information or actions from the user. Common next steps include: