Request a Credential

Overview

Requesting credentials from users is a common requirement for applications on the SELF network. For example, a DeFi app may request a verifiable credential attesting to a user's credit score, while a job portal may request credentials for work experience or education.

The process of requesting a credential involves creating a custom challenge that references the schema of the credential being requested. When a user responds to the challenge, they share the requested credential with your application if they have it in their SELF wallet. Your application can then verify the credential and grant access to the user if the credential is valid and meets your application's requirements.

Attesting a verifiable credential involves two steps:

1. Creating a custom challenge requiring one or more specific credentials.
2. Verifying the credential(s) delivered in response to the challenge.

note

Ensure that Keymaster is installed, initialized, and started as described in the Keymaster installation documentation before creating a schema.

Create a Custom Challenge

const schemaDID =
  "did:test:z3v8AuagJiXARFGw3B8Mc6DrLBC2thMzjgeUZWQvHcyPVBxAYZw";

const challengeData = {
  challenge: {
    credentials: [
      {
        schema: schemaDID,
      },
    ],
    callback: "<YOUR_RESPONSE_API_ENDPOINT>",
  },
};

const challenge = await Keymaster.createChallenge(challengeData);
return challenge;

Following challenge creation, you must present the challenge data to your user in the form of a QR code and/or universal links to the SELF mobile app.

The SELF mobile app will automatically search for the requested credentials upon scanning the QR code or rendering the universal link. If the user has a credential that references the schemaDID included in the challenge, the app will prompt the user to share the credential with your application in response to the challenge. If the user's wallet does not contain one of the requested credentials then they are unable to respond to the challenge.

In the case that the user has the requested credentials and shares them, your application receives a challenge response via an exposed HTTP route. This route should facilitate POST requests and is available via the callback URL configured in the original challenge.

Your application can then verify the credential delivered via the response and grant access to the user if:

• the credential is valid,
• was generated using the expected schemaDID,
• was attested by the expected attestor.

Handle, Decrypt, and Verify Challenge Response

const verifyResponse = async (responseDID: string, options?: any) => {
    const { retries = 5, delay = 2000 } = options || {};

    const response: ChallengeResponse = await Keymaster.verifyResponse(
        responseDID,
        {
            retries,
            delay,
        }
    );
};

It is now up to your application to validate the credential delivered via the response. The best practice is to ensure that the credential is derived from the expected schemaDID and attested by the expected attestorDID.

The attestorDID is the DID of the entity that issued the credential to the user. Your system should know the expected attestorDID per the business logic associated with the requested credential. You can obtain the attestorDID by resolving the credential DID delivered in the response and inspecting the credential metadata.

If both of these conditions are true, you can grant access to the user. If either of these conditions are false, you should deny access to the user.