Quickstart ⚡

Issue and verify a verifiable credential in under 5 minutes

This quickstart will demonstrate the process of defining, issuing, verifying, and revoking a credential. For this exercise, we will issue a credential from Satoshi University for students who complete the Blockchain 101 course.

1. Create a Developer Account

To get started, create a developer account in the Crossmint Staging Console. Open that link, sign in, and accept the dialog to continue.

Crossmint offers two consoles: staging, for development and testing, and production.

2. Get an API key

Once you log in to the console, the next step is to create an API key.

Click the "Integrate" tab and click on the "API Keys" option on top.

Within the Server-side keys section, click the “Create new key” button in the top right. Then, select the scopes credentials:template.create, credentials.read, and credentials.create under the Credentials category and create your key. Save this key for the next step.

These keys are server-side only and should not be exposed in the frontend of a web application.

3. Create a Template

Every Verifiable Credential must belong to a template. Verifiable Credentials within a template share the same schema (referred to as “type” in the template definition), default-metadata, encryption, storage, and chain configurations. A credential template is equivalent to an NFT collection.

For the purpose of this quickstart, we will create a template with the following parameters:

• Type: crossmint:5fe6040e-07a1-48bb-97a3-b588a7e927d2:courseCompletionQuickstart. Types allow you to specify the attributes you are interested in certifying. They also act as a protective measure, preventing the addition of unauthorized fields and, as a result, the tampering of the Verifiable Credential. You can define your own.

• Encryption: none. This means the Verifiable Credential data will be stored in plain text. To encrypt the data, read about the supported encryption modalities.

• Storage: crossmint. This means the Verifiable Credential data will be stored by Crossmint. To store the data at the location of your choice, or in decentralized storage, read about the supported storage modalities.

The credential’s revocation state is stored in the chain provided (polygon-amoy), along with public (non-confidential) metadata related to your credential’s template.

To get started, copy the createVCtemplate.js file below, fill in your API key, and run it in your terminal.

createVCtemplate.js

const myApiKey = ""; // Replace with key from step 2

const templateParams = {
    credentials: {
        // "type" is set to an example type already created by Crossmint for this quickstart
        type: "crossmint:10d52c58-4f69-48db-b3e6-395e64ec84c6:courseCompletionQuickstart",
        encryption: "none",
        storage: "crossmint",
    },
    metadata: {
        name: "Satoshi University Credentials",
        description: "Credentials accredited by Satoshi University",
        imageUrl: "https://picsum.photos/400",
    },
    chain: "polygon-amoy",
};

const options = {
    method: "POST",
    headers: {
        "X-API-KEY": myApiKey,
        "Content-Type": "application/json",
    },
    body: JSON.stringify(templateParams),
};

fetch("https://staging.crossmint.com/api/v1-alpha1/credentials/templates/", options)
    .then((response) => response.json())
    .then((response) => console.log(JSON.stringify(response)))
    .catch((err) => console.error(err));

node createVCtemplate.js

4. Issue a Credential

With a template created, we can start issuing credentials. To do this, we need to enter the subject’s email address, or wallet address, if they have one.

Then, we need to specify the exact data required by the Verifiable Credential type, i.e. course name and grade. The credential’s contents are identified by the “subject” key within the credential.

If you don’t include an expiration date, the credential will not expire. You can always revoke the credential in the future, if necessary.

The credential subject (credential.subject) must respect the schema of the chosen Verifiable Credential type. You cannot add additional fields, nor exclude any that were previously set.

To issue your first credential, copy the issueCredential.js file from below, add your API key, and templateId (that was returned from the previous step), and run the file from your terminal.

issueCredential.js

const userEmail = "[e-mail]"; // Replace with recipient email
const templateId = "YOUR_TEMPLATE_ID"; // Replace with ID from previous step

const credentialParams = {
    recipient: `email:${userEmail}:polygon-amoy`,
    credential: {
        // The courseCompletionQuickstart credential type requires course and grade declarations
        subject: {
            course: "Blockchain 101",
            grade: "A",
        },
        expiresAt: "2034-02-02",
    },
};

const options = {
    method: "POST",
    headers: {
        "X-API-KEY": "YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    body: JSON.stringify(credentialParams),
};

fetch(`https://staging.crossmint.com/api/v1-alpha1/credentials/templates/${templateId}/vcs`, options)
    .then((response) => response.json())
    .then((response) => console.log(JSON.stringify(response)))
    .catch((err) => console.error(err));

node issueCredential.js

Congrats 🎉 you have issued your first credential.

You can set up a webhook to know when the Verifiable Credential NFT minting is completed, or call the action status API with the returned actionId.

5. Retrieve a Credential

​​You can retrieve a Verifiable Credential using different identifiers associated with the credential itself or the NFT associated with the credential.

• Get Verifiable Credential by ID uses the format: urn:uuid:<UUID>
• Get Verifiable Credential by NFT Locator uses the format: <chain>:<contractAddress>:<tokenId>
• Get Verifiable Credential by NFT ID uses crossmint’s internal NFT ID

There is no access control on credential retrieval, credential data is public and can be retrieved by anyone, use encrypted credentials if you need to protect the data.

To retrieve the credential, copy the retrieveCredential.js file from below, use your API key, the credentialId, and run the file from your terminal.

retrieveCredential.js

const options = {
    method: "GET",
    headers: {
        "X-API-KEY": "YOUR_API_KEY",
    },
};

fetch(`https://staging.crossmint.com/api/v1-alpha1/credentials/${credentialId}`, options)
    .then((response) => response.json())
    .then((response) => console.log(JSON.stringify(response)))
    .catch((err) => console.error(err));

node retrieveCredential.js

6. Verify a Credential

Verifying a credential can be done in different ways, the easiest one is to call the verify-credential API. You can also accomplish this with the SDK.

To verify the credential, copy the verifyCredential.js file from below, use your API key, the credentialId, and run the file from your terminal.

verifyCredential.js

const options = {
    method: "POST",
    headers: {
        "X-API-KEY": "YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    body: `{"credential": ${JSON.stringify(credential.unencryptedCredential)}}`,
};

fetch("https://staging.crossmint.com/api/v1-alpha1/credentials/verification/verify", options)
    .then((response) => response.json())
    .then((response) => console.log(JSON.stringify(response)))
    .catch((err) => console.error(err));

node verifyCredential.js

7. Revoke a Credential

To revoke a credential, you can directly use the revoke credential API. Copy the revokeCredential.js file from below, use your API key, the credentialId, and run the file from your terminal.

revokeCredential.js

const options = {
    method: "DELETE",
    headers: {
        "X-API-KEY": "YOUR_API_KEY",
    },
};

fetch(`https://staging.crossmint.com/api/v1-alpha1/credentials/${credentialId}`, options)
    .then((response) => response.json())
    .then((response) => console.log(JSON.stringify(response)))
    .catch((err) => console.error(err));

node revokeCredential.js