Create a Credential

Tutorial: Create and Send Your First Digital Credential

PreviousYour First Integration NextCreate a Boost

Last updated 15 days ago

Was this helpful?

Create a Credential

Tutorial: Create and Send Your First Digital Credential

Welcome! This tutorial will walk you through creating your very first digital Verifiable Credential (VC) and sending it to your LearnCard app. Think of a VC as a secure, digital certificate or badge that can prove something, like an achievement or a skill.

What you'll accomplish:

Set up a simple "Issuer" environment using the LearnCard SDK.
Design and create a "Workshop Completion" Verifiable Credential.
Digitally sign (issue) the credential to make it official.
Send this credential to your own LearnCard app using your Profile ID.
View the received credential in your LearnCard app.

Why is this useful? Understanding this basic flow is the first step to building applications that can issue digital badges, certificates, or any other kind of verifiable proof to users, empowering them with portable and trustworthy records.

Prerequisites:

Node Installed: Node.js installed on your computer.

Part 0: Project Setup

# 1. Create a new directory and navigate into it
mkdir learncard-tutorial-1
cd learncard-tutorial-1

# 2. Initialize a Node.js project
npm init -y

# 3. Install LearnCard and the necessary tools for this tutorial
npm install @learncard/init @learncard/core @learncard/types dotenv 
npm install --save-dev typescript tsx @types/node

# 4. Create a TypeScript configuration file
npx tsc --init --rootDir ./ --outDir ./dist --esModuleInterop --resolveJsonModule --lib es2022 --module esnext  --moduleResolution node

# 1. Create a new directory and navigate into it
mkdir learncard-tutorial-js-1
cd learncard-tutorial-js-1

# 2. Initialize a Node.js project
npm init -y

# 3. Install LearnCard and the necessary tools for this tutorial
npm install @learncard/init @learncard/core dotenv

Open the package.json file that was created in your learncard-tutorial-js directory and add the following line:

{
  "name": "learncard-tutorial-js-1",
  "version": "1.0.0",
  // ... other fields ...
  "type": "module"  // <--- Add this line
}

Part 1: Setting Up Your Issuer Environment

For this tutorial, your computer will act as the "Issuer" – the entity creating and sending the credential.

Step 1.1: Create an Issuer Script

Create a new file in your project folder: issueCredential.ts

Create a new file in your project folder: issueCredential.js

Step 1.2: Initialize LearnCard SDK for the Issuer

This instance will represent your workshop organization.

issueCredential.ts

import "dotenv/config";

import { NetworkLearnCardFromSeed, initLearnCard } from "@learncard/init";
import { UnsignedVC, VC, LCNProfile } from "@learncard/types";

async function setupIssuerLearnCard() {
  const issuerSeed = process.env.SECURE_SEED;

  if (!issuerSeed) {
    throw new Error(
      "Can not initialize LearnCard without a secure seed. Please create an .env file with SECURE_SEED set as a 64-digit string."
    );
  }

  const learnCardIssuer: NetworkLearnCardFromSeed['returnValue'] = await initLearnCard({
    seed: issuerSeed, // This generates the Issuer's DID and keys
    network: true, // We need network capabilities to send the credential
    allowRemoteContexts: true, // We will issue a credential with a remote context
  });

  console.log("Issuer LearnCard Initialized.");
  console.log("Issuer DID:", learnCardIssuer.id.did());
  return learnCardIssuer;
}
// (We'll call this function later)

issueCredential.js

import "dotenv/config";

import { initLearnCard } from "@learncard/init";

async function setupIssuerLearnCard() {
  const issuerSeed = process.env.SECURE_SEED;

  if (!issuerSeed) {
    throw new Error(
      "Can not initialize LearnCard without a secure seed. Please create an .env file with SECURE_SEED set as a 64-digit string."
    );
  }

  const learnCardIssuer = await initLearnCard({
    seed: issuerSeed, // This generates the Issuer's DID and keys
    network: true, // We need network capabilities to send the credential
    allowRemoteContexts: true, // We will issue a credential with a remote context
  });

  console.log("Issuer LearnCard Initialized.");
  console.log("Issuer DID:", learnCardIssuer.id.did());
  return learnCardIssuer;
}
// (We'll call this function later)

This code initializes a LearnCard instance.

Step 1.3: Ensure Issuer Has a Service Profile

To interact with the LearnCard Network effectively (like sending credentials), your Issuer's DID should be associated with a Service Profile.

Add this function to issueCredential.ts

async function ensureIssuerProfile(learnCardIssuer: NetworkLearnCardFromSeed['returnValue']) {
  const issuerServiceProfileData: Omit<LCNProfile, 'did' | 'isServiceProfile'> = {
    profileId: process.env.PROFILE_ID!,
    displayName: process.env.PROFILE_NAME!,
    bio: '',
    shortBio: '',
    // Add other relevant details for your issuer profile
  };

  if (!issuerServiceProfileData.profileId) {
    throw new Error(
      "Please create an .env file with PROFILE_ID set as a unique, 3-40 character string. e.g: my-organization-id."
    );
  }
  if (!issuerServiceProfileData.displayName) {
    throw new Error(
      'Please create an .env file with PROFILE_NAME set as human readable string, e.g: "My Organization".'
    );
  }

  try {
    // Check if profile exists first, to avoid errors if run multiple times
    let profile = await learnCardIssuer.invoke.getProfile(
      issuerServiceProfileData.profileId
    );
    if (!profile) {
      console.log(
        `Creating service profile for issuer: ${issuerServiceProfileData.profileId}`
      );
      await learnCardIssuer.invoke.createServiceProfile(
        issuerServiceProfileData
      );
      console.log("Issuer Service Profile created successfully.");
    } else {
      console.log("Issuer Service Profile already exists.");
    }
  } catch (error: any) {
    console.error("Error ensuring issuer profile:", error.message);
  }
}
// (We'll call this after setupIssuerLearnCard)

Add this function to issueCredential.js

async function ensureIssuerProfile(learnCardIssuer) {
  const issuerServiceProfileData = {
    profileId: process.env.PROFILE_ID,
    displayName: process.env.PROFILE_NAME,
  };

  if (!issuerServiceProfileData.profileId) {
    throw new Error(
      "Please create an .env file with PROFILE_ID set as a unique, 3-40 character string. e.g: my-organization-id."
    );
  }
  if (!issuerServiceProfileData.displayName) {
    throw new Error(
      'Please create an .env file with PROFILE_NAME set as human readable string, e.g: "My Organization".'
    );
  }

  try {
    let profile = await learnCardIssuer.invoke.getProfile(
      issuerServiceProfileData.profileId
    );
    if (!profile) {
      console.log(
        `Creating service profile for issuer: ${issuerServiceProfileData.profileId}`
      );
      await learnCardIssuer.invoke.createServiceProfile(
        issuerServiceProfileData
      );
      console.log("Issuer Service Profile created successfully.");
    } else {
      console.log("Issuer Service Profile already exists.");
    }
  } catch (error) {
    console.error("Error ensuring issuer profile:", error.message);
  }
}

Step 1.4: Generate Secure Seed and .env file

Create and save your seed to .env:

Run the following command in your terminal:

echo "SECURE_SEED=\"$(node -e "console.log(require('crypto').randomBytes(32).toString('hex'))")\"" > .env

Run the following command in your Windows cmd prompt:

echo "SECURE_SEED=\"$(node -e "console.log(require('crypto').randomBytes(32).toString('hex'))")\"" > .env

Run the following command in Powershell:

"SECURE_SEED=\"$(node -e "console.log(require('crypto').randomBytes(32).toString('hex'))")\"" | Out-File -Encoding utf8 .env

Add config variables to your `.env`:

You must create a unique profile ID for your organization. It must be 3-40 characters, lowercase, no spaces or special characters. E.g.: my-organization, acme, taffy-co-organization , etc.

.env

SECURE_SEED="..." # Created from command in prior step.
PROFILE_ID="<unique-profile-id>" # Unique profile ID.
PROFILE_NAME="<Display Name>" # Human Readable Display Name

Part 2: Designing Your "Workshop Completion" Credential

Now, let's define what information our "Workshop Completion" credential will hold.

Step 2.1: Retrieve Your LearnCard Profile ID

How to Find:

Step 2.1: Define the Credential Content

A Verifiable Credential is a set of claims made by an Issuer about a Subject (the recipient).

// Add this to issueCredential.ts

// IMPORTANT: Replace with the Profile ID you got from YOUR LearnCard App
const recipientProfileId = 'YOUR_LEARNCARD_APP_PROFILE_ID'; 

async function generateWorkshopCredentialForRecipient(
  learnCardIssuer: NetworkLearnCardFromSeed['returnValue'],
  recipientProfileId: string
): Promise<UnsignedVC> {
  // Retrieve recipient profile to retrieve their DID
  const recipientProfile = await learnCardIssuer.invoke.getProfile(
    recipientProfileId
  );
  if (!recipientProfile) {
    throw new Error(
      "Recipient LearnCard Profile ID does not exist in LearnCloud Network."
    );
  }

  // This will also be the credentialSubject.id if the credential is about the recipient directly.
  const recipientDidForCredential = recipientProfile.did;

  const workshopCredentialContent: UnsignedVC = {
    // "@context" defines the vocabulary used (like a dictionary for terms)
    "@context": [
      "https://www.w3.org/2018/credentials/v1",
      "https://purl.imsglobal.org/spec/ob/v3p0/context-3.0.1.json",
      "https://ctx.learncard.com/boosts/1.0.0.json",
    ],
    // "type" specifies what kind of credential this is
    type: ["VerifiableCredential", "OpenBadgeCredential", "BoostCredential"], // Standard VC type + OpenBadge type + Boost type
    issuanceDate: new Date().toISOString(), // Today's date
    issuer: learnCardIssuer.id.did(),
    name: "LearnCard Basics Workshop",
    // "credentialSubject" is about whom or what the credential is
    credentialSubject: {
      achievement: {
        achievementType: "Badge",
        criteria: {
          narrative:
            "Awarded for successfully completing the interactive LearnCard tutorial.",
        },
        description:
          "This badge was generated in the CodePen demonstration project in the LearnCard Developer Docs.",
        id: "urn:uuid:" + crypto.randomUUID(), // Generate a unique ID
        image: "https://example.com/badge-images/teamwork.png",
        name: "LearnCard Basics Workshop",
        type: ["Achievement"],
      },
      id: recipientDidForCredential, // The DID of the person who completed the workshop
      type: ["AchievementSubject"],
    },
    // Additional Boost Display Fields for Extra Customization
    display: {
      backgroundColor: "#40cba6",
      displayType: "badge",
    },
    image: "https://cdn.filestackcontent.com/YjQDRvq6RzaYANcAxKWE",
    // "proof" will be added automatically when the credential is signed
  };

  return workshopCredentialContent;
}

// Add this to issueCredential.js

// IMPORTANT: Replace with the Profile ID you got from YOUR LearnCard App
const recipientProfileId = 'YOUR_LEARNCARD_APP_PROFILE_ID'; 

async function generateWorkshopCredentialForRecipient(
  learnCardIssuer: NetworkLearnCardFromSeed,
  recipientProfileId: string
): Promise<UnsignedVC> {
  // Retrieve recipient profile to retrieve their DID
  const recipientProfile = await learnCardIssuer.invoke.getProfile(
    recipientProfileId
  );
  if (!recipientProfile) {
    throw new Error(
      "Recipient LearnCard Profile ID does not exist in LearnCloud Network."
    );
  }

  // This will also be the credentialSubject.id if the credential is about the recipient directly.
  const recipientDidForCredential = recipientProfile.did;

  const workshopCredentialContent: UnsignedVC = {
    // "@context" defines the vocabulary used (like a dictionary for terms)
    "@context": [
      "https://www.w3.org/2018/credentials/v1",
      "https://purl.imsglobal.org/spec/ob/v3p0/context-3.0.1.json",
      "https://ctx.learncard.com/boosts/1.0.0.json",
    ],
    // "type" specifies what kind of credential this is
    type: ["VerifiableCredential", "OpenBadgeCredential", "BoostCredential"], // Standard VC type + OpenBadge type + Boost type
    issuanceDate: new Date().toISOString(), // Today's date
    issuer: learnCardIssuer.id.did(),
    name: "LearnCard Basics Workshop",
    // "credentialSubject" is about whom or what the credential is
    credentialSubject: {
      achievement: {
        achievementType: "Badge",
        criteria: {
          narrative:
            "Awarded for successfully completing the interactive LearnCard tutorial.",
        },
        description:
          "This badge was generated in the CodePen demonstration project in the LearnCard Developer Docs.",
        id: "urn:uuid:" + crypto.randomUUID(), // Generate a unique ID
        image: "https://example.com/badge-images/teamwork.png",
        name: "LearnCard Basics Workshop",
        type: ["Achievement"],
      },
      id: recipientDidForCredential, // The DID of the person who completed the workshop
      type: ["AchievementSubject"],
    },
    // Additional Boost Display Fields for Extra Customization
    display: {
      backgroundColor: "#40cba6",
      displayType: "badge",
    },
    image: "https://cdn.filestackcontent.com/YjQDRvq6RzaYANcAxKWE",
    // "proof" will be added automatically when the credential is signed
  };

  return workshopCredentialContent;
}

✨ Key Points:

@context: Tells systems how to interpret the fields.
type: Helps categorize the credential. VerifiableCredential is standard.
credentialSubject: This is the core information. The id here should be the DID of the person receiving the credential. For this tutorial, we're using the recipientProfileId (which you got from your app) to construct a DID.

Part 3: Creating and Signing the Credential (Issuance)

Let's take the content and make it an official, signed Verifiable Credential.

Step 3.1: "Issue" / "Sign" the Unsigned Credential

The LearnCard SDK helps you with this:

// Add this function to issueCredential.ts

async function createAndSignCredential(
  learnCardIssuer: NetworkLearnCardFromSeed['returnValue'],
  unsignedVc: UnsignedVC
) {
  console.log("Unsigned VC:", JSON.stringify(unsignedVc, null, 2));

  console.log("Now signing (issuing) the credential...");
  const signedVc = await learnCardIssuer.invoke.issueCredential(unsignedVc);
  console.log("Signed VC created successfully!");
  console.log(JSON.stringify(signedVc, null, 2));
  return signedVc;
}

// (We'll call this later)

// Add this function to issueCredential.js

async function createAndSignCredential(learnCardIssuer, unsignedVc) {
  console.log("Unsigned VC:", JSON.stringify(unsignedVc, null, 2));

  console.log("Now signing (issuing) the credential...");
  const signedVc = await learnCardIssuer.invoke.issueCredential(unsignedVc);
  console.log("Signed VC created successfully!");
  console.log(JSON.stringify(signedVc, null, 2));
  return signedVc;
}

// (We'll call this later)

issueCredential adds the issuer's DID, issuance date, and a cryptographic signature, making it verifiable.

Part 4: Sending the Credential to Your LearnCard App

Now, let's send this official credential to your LearnCard app.

Step 4.1: Use `sendCredential`

This function from the LearnCard SDK (via the Network plugin) handles the delivery.

// Add this function to issueCredential.ts

async function sendVcToRecipient(
  learnCardIssuer: NetworkLearnCardFromSeed['returnValue'],
  recipientLcnProfileId: string,
  signedVc: VC
) {
  console.log(`Sending credential to Profile ID: ${recipientLcnProfileId}`);
  try {
    const sentCredentialUri = await learnCardIssuer.invoke.sendCredential(
      recipientLcnProfileId,
      signedVc,
    );
    console.log(
      "Credential sent successfully! Sent Credential URI:",
      sentCredentialUri
    );
    return sentCredentialUri;
  } catch (error) {
    console.error("Error sending credential:", error);
    throw error;
  }
}

// (We'll call this later)

// Add this function to issueCredential.js

async function sendVcToRecipient(
  learnCardIssuer,
  recipientLcnProfileId,
  signedVc
) {
  console.log(`Sending credential to Profile ID: ${recipientLcnProfileId}`);
  try {
    const sentCredentialUri = await learnCardIssuer.invoke.sendCredential(
      recipientLcnProfileId,
      signedVc
    );
    console.log(
      "Credential sent successfully! Sent Credential URI:",
      sentCredentialUri
    );
    return sentCredentialUri;
  } catch (error) {
    console.error("Error sending credential:", error);
    throw error;
  }
}

Part 5: Putting It All Together & Viewing in Your App

Let's create a main function to run these steps.

Step 5.1: Main Script Logic

// Add this main execution block at the end of issueCredential.ts

async function main() {
  // @ts-ignore
  if (recipientProfileId === "YOUR_LEARNCARD_APP_PROFILE_ID") {
    console.error(
      "Please replace 'YOUR_LEARNCARD_APP_PROFILE_ID' with your actual Profile ID from the LearnCard app in the 'recipientProfileId' variable."
    );
    return;
  }

  const learnCardIssuer = await setupIssuerLearnCard();
  await ensureIssuerProfile(learnCardIssuer);
  const workshopCredential = await generateWorkshopCredentialForRecipient(
    learnCardIssuer,
    recipientProfileId
  );

  const signedVc = await createAndSignCredential(
    learnCardIssuer,
    workshopCredential
  );

  if (signedVc) {
    await sendVcToRecipient(learnCardIssuer, recipientProfileId, signedVc);
    console.log(
      "\nTutorial complete! Check your LearnCard app for the new credential."
    );
    console.log("It might take a moment to receive a notification.");
  } else {
    console.log("Credential creation or signing failed. Cannot send.");
  }
}

main().catch((err) => console.error("Tutorial encountered an error:", err));

// Add this main execution block at the end of issueCredential.js

async function main() {

  if (recipientProfileId === "YOUR_LEARNCARD_APP_PROFILE_ID") {
    console.error(
      "Please replace 'YOUR_LEARNCARD_APP_PROFILE_ID' with your actual Profile ID from the LearnCard app in the 'recipientProfileId' variable."
    );
    return;
  }

  const learnCardIssuer = await setupIssuerLearnCard();
  await ensureIssuerProfile(learnCardIssuer);
  const workshopCredential = await generateWorkshopCredentialForRecipient(
    learnCardIssuer,
    recipientProfileId
  );

  const signedVc = await createAndSignCredential(
    learnCardIssuer,
    workshopCredential
  );

  if (signedVc) {
    await sendVcToRecipient(learnCardIssuer, recipientProfileId, signedVc);
    console.log(
      "\nTutorial complete! Check your LearnCard app for the new credential."
    );
    console.log("It might take a moment to receive a notification.");
  } else {
    console.log("Credential creation or signing failed. Cannot send.");
  }
}

main().catch((err) => console.error("Tutorial encountered an error:", err));

Step 5.2: Run Your Script

Replace Placeholders:
- In issueCredential.ts, find YOUR_LEARNCARD_APP_PROFILE_ID and replace it with the Profile ID you copied from your LearnCard app.
- Ensure .env file contains SECURE_SEED, PROFILE_ID, and PROFILE_NAME with your own unique values set,
Save the file.
Open your terminal in your project directory and run:
- npx tsx issueCredential.ts

Replace Placeholders:
- In issueCredential.js, find YOUR_LEARNCARD_APP_PROFILE_ID and replace it with the Profile ID you copied from your LearnCard app.
- Ensure .env file contains SECURE_SEED, PROFILE_ID, and PROFILE_NAME with your own unique values set,
Save the file.
Open your terminal in your project directory and run:
- node issueCredential.js

Step 5.3: View in Your LearnCard App

Summary & What's Next

Congratulations! You've successfully: ✅ Set up a basic Issuer using the LearnCard SDK. ✅ Defined, created, and digitally signed a Verifiable Credential. ✅ Sent that credential to your own LearnCard app.

This tutorial covers the fundamental flow of issuing credentials. From here, you can explore:

Integrating this issuance logic into your own applications and backend services.

Explore the rest of our documentation to learn more about the powerful features of LearnCard!

PreviousYour First Integration NextCreate a Boost

Last updated 15 days ago

Was this helpful?

What you'll accomplish:

Prerequisites:

Part 0: Project Setup

Part 1: Setting Up Your Issuer Environment

Step 1.1: Create an Issuer Script

Step 1.2: Initialize LearnCard SDK for the Issuer

Step 1.3: Ensure Issuer Has a Service Profile

Step 1.4: Generate Secure Seed and .env file

Create and save your seed to .env:

Add config variables to your .env:

Part 2: Designing Your "Workshop Completion" Credential

Step 2.1: Retrieve Your LearnCard Profile ID

How to Find:

Step 2.1: Define the Credential Content

Part 3: Creating and Signing the Credential (Issuance)

Step 3.1: "Issue" / "Sign" the Unsigned Credential

Part 4: Sending the Credential to Your LearnCard App

Step 4.1: Use sendCredential

Part 5: Putting It All Together & Viewing in Your App

Step 5.1: Main Script Logic

Step 5.2: Run Your Script

Step 5.3: View in Your LearnCard App

Summary & What's Next

What you'll accomplish:

Prerequisites:

Part 0: Project Setup

Part 1: Setting Up Your Issuer Environment

Step 1.1: Create an Issuer Script

Step 1.2: Initialize LearnCard SDK for the Issuer

Step 1.3: Ensure Issuer Has a Service Profile

Step 1.4: Generate Secure Seed and .env file

Create and save your seed to .env:

Add config variables to your .env:

Part 2: Designing Your "Workshop Completion" Credential

Step 2.1: Retrieve Your LearnCard Profile ID

How to Find:

Step 2.1: Define the Credential Content

Part 3: Creating and Signing the Credential (Issuance)

Step 3.1: "Issue" / "Sign" the Unsigned Credential

Part 4: Sending the Credential to Your LearnCard App

Step 4.1: Use sendCredential

Part 5: Putting It All Together & Viewing in Your App

Step 5.1: Main Script Logic

Step 5.2: Run Your Script

Step 5.3: View in Your LearnCard App

Summary & What's Next

Add config variables to your `.env`:

Step 4.1: Use `sendCredential`

Add config variables to your `.env`:

Step 4.1: Use `sendCredential`