Requesting Claims
A Claim is the core concept in DID Connect for specifying what information an application needs from a user's wallet. All claim requests are defined within the claims object when you use handlers.attach to set up a session endpoint.
This guide covers the three primary methods for requesting claims: for a single piece of information, for multiple pieces of information at once, and for information that is determined dynamically after a user connects.
Requesting a Single Claim#
The most common scenario is requesting a single piece of information, such as a user's profile. To do this, you define a key in the claims object that corresponds to the desired claim type. The value is a function that returns the claim's specific configuration.
// From README.md
handlers.attach({
action: 'profile',
claims: {
// Request a single 'profile' claim
profile: () => ({
fields: ['fullName', 'email'],
description: 'Please provide your name and email to continue',
}),
},
onAuth: async ({ userDid, claims }) => {
// The 'claims' array will contain the submitted profile data
const profile = claims.find((x) => x.type === 'profile');
console.info('Login successful:', { userDid, profile });
},
});In this example, we request a profile claim. The user's wallet will prompt them to share their full name and email. After the user approves, the onAuth callback receives the submitted information in the claims array.
Requesting Multiple Claims#
DID Connect can request several different pieces of information within a single session. This is useful for more complex interactions, like a registration process that requires both a user profile and proof of ownership of a specific digital asset.
Requesting Different Claim Types#
To request claims of different types, simply add more keys to the claims object.
// From README.md
handlers.attach({
action: 'multiple-claims',
claims: {
profile: () => ({
fields: ['fullName', 'email'],
description: 'Please provide your name and email to continue',
}),
asset: ({ userDid }) => {
// The userDid is available if you need it to customize the claim
return {
description: 'Please provide a valid NFT',
trustedIssuers: ['z82e...'], // DID of the NFT contract issuer
};
},
},
onAuth: async ({ claims, userDid }) => {
// 'claims' is an array containing both the profile and the asset claim results
},
});Here, the wallet will present both requests to the user in a single flow. The onAuth callback then receives an array containing the results for both the profile and asset claims.
Requesting Multiple Claims of the Same Type#
If you need to request multiple claims of the same type—for instance, asking a user to sign two different messages—you must provide unique keys for each request. The value for each key should be an array containing the claim type as the first element and the configuration object as the second.
// Based on README.md and ocap-playground/api/routes/auth/claim-multiple.js
handlers.attach({
action: 'multiple-signatures',
claims: {
// 'signText' is a custom identifier for this specific request
signText: [
'signature', // The actual claim type
{
type: 'mime:text/plain',
data: 'I agree to the terms of service.',
description: 'Sign the text to continue',
},
],
// 'signHtml' is another custom identifier
signHtml: [
'signature', // The same claim type, but a different request
{
type: 'mime:text/html',
data: `<h2>Transaction Summary</h2><p>Amount: 1 OCAP</p>`,
description: 'Sign the HTML to confirm the transaction',
},
],
},
onAuth: async ({ claims, userDid }) => {
// 'claims' contains results for both signature requests
},
});Using custom keys like signText and signHtml is required to differentiate the results for each signature request within the onAuth callback.
Dynamic Claims#
In some cases, the information you need to request depends on who the user is. For example, you might only ask for a verifiable credential if the user's profile indicates they are from a certain region. The onConnect lifecycle callback lets you define claims dynamically after the user has connected their wallet but before the claims are sent.
// Based on README.md and ocap-playground/api/routes/auth/claim-dynamic.js
handlers.attach({
action: 'dynamic-claims',
// This callback runs after the user scans the QR code and connects their wallet.
onConnect: async ({ userDid }) => {
// Here you can add business logic based on the user's DID.
// For example, check a database to see if the user is new.
const isNewUser = await checkUserRegistration(userDid);
if (isNewUser) {
// Return a claims object to be sent to the wallet.
return {
profile: () => ({
fields: ['fullName', 'email'],
description: 'Welcome! Please provide your name and email to register.',
}),
};
}
// If the user is already known, we can request a simple signature.
return {
signature: () => ({
type: 'mime:text/plain',
data: getRandomMessage(),
description: 'Please sign this message to log in.',
}),
};
},
onAuth: async ({ claims, userDid }) => {
// 'claims' will contain the result for the dynamically generated claim(s).
},
});The onConnect function is executed as soon as the wallet provides the userDid. This allows you to perform server-side checks and return a tailored claims object for that specific user and session. If onConnect returns a claims object, it will override any static claims defined on the handler.
Next Steps#
You have learned the three primary ways to request information from a user's wallet. Each method provides flexibility for different application requirements.