Requesting Claims
In a DID Connect session, a "claim" is a specific piece of information or action you request from a user's wallet. This could be anything from their name and email to a cryptographic signature proving ownership of an asset. This guide will walk you through the different ways to request claims from a user.
All claim requests are configured within the claims property of the handlers.attach method. For a full list of available claim types and their parameters, please see the Claims Reference.
Requesting a Single Claim#
The most straightforward use case is requesting a single piece of information. You define a claims object where each key represents a specific claim you want to request. The value is typically a function that returns the claim's definition object.
For example, to request a user's profile containing their full name and email, you would configure it as follows:
Basic Profile Claim
handlers.attach({
action: 'profile',
claims: {
// The key 'profile' specifies the claim type.
// The value is a function that returns the claim's parameters.
profile: () => ({
fields: ['fullName', 'email'],
description: 'Please provide your name and email to continue',
}),
},
onAuth: async ({ userDid, claims }) => {
// The 'claims' array contains the data submitted by the user.
try {
const profile = claims.find((x) => x.type === 'profile');
console.info('login.success', { userDid, profile });
} catch (err) {
console.error('login.error', err);
}
},
});In this example, we request a single profile claim. The wallet will prompt the user to share their full name and email. Once the user approves, the onAuth callback receives the submitted information in the claims array.
Requesting Multiple Claims#
DID Connect allows you to request multiple pieces of information in a single session, which is highly efficient. There are two ways to do this, depending on whether the claims are of different types or the same type.
Multiple Different Claims#
To request several different types of claims at once, simply add more key-value pairs to the claims object. For instance, you can ask for a user's profile and proof of ownership of a specific asset in the same session.
Multiple Different Claims
handlers.attach({
action: 'multiple-claims',
claims: {
profile: () => ({
fields: ['fullName', 'email'],
description: 'Please provide your name and email to continue',
}),
asset: ({ userDid, extraParams }) => {
// The asset claim can be a function to dynamically set parameters
return {
description: 'Please prove ownership of a valid NFT',
trustedIssuers: ['z1...', 'z2...'], // Optional: filter by trusted NFT issuers
};
},
},
onAuth: async ({ claims, userDid }) => {
// `claims` is an array containing both the profile and the asset claim results.
const profile = claims.find(c => c.type === 'profile');
const asset = claims.find(c => c.type === 'asset');
console.log({ userDid, profile, asset });
},
});Multiple Claims of the Same Type#
If you need to request multiple claims of the same type (e.g., asking the user to sign two different messages), you need a slightly different syntax. You use a unique key for each request and provide the claim type and its definition as a two-element array.
Here's how to request two different signature claims:
Multiple Same-Type Claims
handlers.attach({
action: 'multiple-signatures',
claims: {
// 'signText' is a unique identifier for this specific request.
signText: [
'signature', // The first element is the claim type as a string.
{ // The second element is the claim definition object.
type: 'mime:text/plain',
data: 'I agree to the terms of service.',
description: 'Please sign the text to continue',
},
],
// 'signHtml' is another unique identifier.
signHtml: [
'signature',
{
type: 'mime:text/html',
data: `<h2>Transaction Summary</h2><p>Amount: 100 ABC</p>`,
description: 'Please sign to confirm the transaction',
},
],
},
onAuth: async ({ claims, userDid }) => {
// `claims` will contain the results for both signature requests.
console.log('User signed messages:', claims);See all 2 lines
Dynamic Claims#
In some scenarios, the information you need to request depends on who the user is. For example, you might want to request a KYC (Know Your Customer) credential only if the user hasn't provided one before. This can be achieved using dynamic claims with the onConnect lifecycle callback.
The onConnect callback runs after the user has scanned the QR code and selected a DID in their wallet, but before the claims are sent to them. This gives you access to the user's DID (userDid) to perform business logic.
Dynamic Claims with onConnect
handlers.attach({
action: 'dynamic-claims',
// This function runs after the wallet connects but before claims are requested.
onConnect: async ({ userDid }) => {
// Example: Check if the user needs to provide a profile.
const userExists = await checkUserInDatabase(userDid);
if (!userExists) {
// Return a claims object to request the needed information.
return {
profile: () => ({
fields: ['fullName', 'email'],
description: 'Please create your profile to continue',
}),
};
}
// If no claims are needed, return null or an empty object.
return {};
},
onAuth: async ({ claims, userDid }) => {
// `claims` will contain the result for the dynamically requested claim, if any.
if (claims.length > 0) {See all 4 lines
By returning a claims object from onConnect, you can tailor the DID Connect session to each user's specific context, creating a more intelligent and streamlined experience.
Now that you know how to request information from the user, the next step is to learn how to process their responses.