Verifiable Credential Claim

A Verifiable Credential (VC) is a digital tamper-proof credential that can be used to prove something about the holder. The Verifiable Credential claim allows your application to request that a user present a specific VC from their DID Wallet to prove an attribute, qualification, or entitlement.

This is a powerful way to verify information without needing to contact the original issuer every time. Common use cases include:

• Verifying a user's age without revealing their birthdate.
• Confirming membership in an organization.
• Proving ownership of a ticket or pass.
• Gating access to content based on a specific achievement or certificate.

How to Request a Verifiable Credential#

To request a Verifiable Credential, you include a verifiableCredential object in the claims array when creating a DID Connect session. You can specify various criteria to filter the exact credential you need from the user's wallet.

const handlers = new WalletHandlers({
  authenticator,
  // ... other configurations
});

app.get('/api/auth/login', async (req, res) => {
  const claims = {
    verifiableCredential: {
      description: 'Please present your Blocklet Server Passport to continue.',
      filters: [
        {
          type: ['BlockletServerPassport'],
          trustedIssuers: ['zNKjDm4Xsoaffb19UE6Q_YOUR_ISSUER_DID_HERE'], // Example Issuer DID
        },
      ],
    },
  };

  // The wallet will prompt the user to select a matching credential
  return handlers.auth(req, res, claims);
});

Parameters#

The verifiableCredential claim object accepts the following parameters to define the request:

Parameter	Type	Description
description	string	Required. A message displayed to the user in their wallet, explaining why the credential is being requested.
optional	boolean	If set to true, the user can skip this claim and still proceed. Defaults to false.
filters	array	An array of filter objects. The wallet will find credentials that match any of the filters (logical OR). Within each filter object, all conditions must be met (logical AND). This is the recommended modern approach.
claimUrl	string	A URL where the user can view more information about the claim being requested.
acquireUrl	string	A URL where the user can go to obtain the required credential if they don't already have it.

Filter Object Parameters#

Each object inside the filters array can contain the following fields:

Parameter	Type	Description
type	string[]	An array of acceptable VC type names. The credential must match one of the types in this list.
trustedIssuers	string[]	An array of DIDs. The credential must have been issued by one of these DIDs.
target	string	The DID of the subject to whom the credential was issued. Usually, this is the user's own DID.
tag	string	A specific tag that must be present on the credential.
ownerDid	string[]	An array of DIDs who are allowed to present the credential.

Legacy Parameters#

For backward compatibility, the following parameters can be used at the top level of the claim object. However, using the filters array is the recommended approach for new applications.

• item: (string[]) Alias for filters[0].type.
• trustedIssuers: (string[]) Alias for filters[0].trustedIssuers.
• target: (string) Alias for filters[0].target.
• tag: (string) Alias for filters[0].tag.

Examples#

Requesting a Credential by Type and Issuer#

This is the most common use case. You know what kind of credential you need and who you trust to issue it.

const claims = {
  verifiableCredential: () => ({
    description: 'Please present your Blocklet Server Passport.',
    filters: [
      {
        type: ['BlockletServerPassport'],
        trustedIssuers: ['zNKjDm4Xsoaffb19UE6QxVeevuaTaLCS1n1S'],
      },
    ],
  }),
};

Requesting a Credential with Multiple Criteria#

You can provide multiple filters to give the user more options. For example, you might accept a passport from one issuer OR a membership card with a specific tag from another.

const claims = {
  verifiableCredential: () => ({
    description: 'Please present a valid passport or a tagged membership card.',
    optional: true,
    filters: [
      // Option 1: A specific type of passport from a trusted issuer
      {
        type: ['BlockletServerPassport'],
        trustedIssuers: ['zNKjDm4Xsoaffb19UE6QxVeevuaTaLCS1n1S'],
      },
      // Option 2: Any credential from another issuer that has a specific tag
      {
        trustedIssuers: ['zNKoA97a922N4234UE6QxVeevuaTaLCS1abc'],
        tag: 'gold_member_card',
      },
    ],
  }),
};

In this example, the user can satisfy the request by presenting either a BlockletServerPassport from the first issuer or any credential from the second issuer that is tagged as gold_member_card.

After successfully requesting a Verifiable Credential, you might want to request ownership of a different kind of on-chain data. Learn how to do this in the next section.