Auth Principal Claim

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.

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.

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.

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: