Quickstart: Credential Issuance

If you are looking to issue credentials on chain this guide will help you achieve that.

This Quickstart will walk you through:

• Setting up the AIR Kit
• Defining and issuing credentials to users
• Managing credential issuance flows

What You'll Build

By the end of this Quickstart, you will have:

• A credential schema defined for your app (e.g., membership, role, event pass)
• Code that issues credentials to users after login
• Application logic that handles credential issuance results

Before Starting, Ensure You Have

• Completed or understood the Login & Sessions Quickstart (recommended but not mandatory)
• Node.js v16+ installed

Step 1: Install the AIR Kit

npm install @mocanetwork/airkit

Step 2: Get Your Partner ID

1. Go to the Developer Dashboard and login with your EOA wallet
2. Connect your wallet
3. Navigate to the Accounts section on the navigation bar on the left. Then go to the General section. Copy the Partner ID and Issuer DID from the partner account information and settings

Step 3: Setup JWT Authentication

To issue credentials, you need to set up JWT authentication. This involves configuring your JWKS (JSON Web Key Set) URL and generating authentication tokens.

JWT Setup Required

For detailed instructions on setting up JWT authentication, including JWKS configuration and token generation, please refer to the Partner Authentication guide.

Quick Setup:

1. Navigate to the Accounts Section and configure your JWKS URL
2. Generate JWT tokens using your private key for authentication

Step 4: Create Schema for Credential Issuance

Before issuing credentials, you need to create a schema that defines the structure of your credentials. A schema is a blueprint that specifies what data fields will be included in your credentials.

Schema Creation Guide

For detailed instructions on creating schemas, including best practices, examples, and schema management, please refer to the Schema Creation Guide.

Quick Setup:

1. Go to the Developer Dashboard.
2. Navigate to the Schemas section under Issuer
3. Create a schema of your choice:
   • Input title/schema type/description and click continue
   • Click "+" and add at least one Attribute property
   • Click Publish to make it available

4. Create credentials to be issued. Navigate to the Credentials Section and create the credential with the schema you just created

Issuing Credentials

You can issue credentials using both the SDK and the demo application. Let's look at both methods.

Issuing Credentials Using the Example App

1. Generate a JWT token on the interface

2. Get the configuration details from the Developer Dashboard:

   • Issuer DID and Partner ID from the General page under the Account section
   • Issuance program ID from the Credentials section

3. Go to the Demo app and enter the Issuer ID, Issuance program ID, and the relevant field names and values

4. Click "Start Credential Issuance"

5. The AIR Credential widget will open and guide the user through the issuance process

6. You'll receive a success notification when the process completes and can verify the credentials issued under the records section in the Issuer Tab

---

Issuing Credentials Using the AIR Kit

The AIR Kit provides a convenient way to issue and verify digital credentials directly in your web application using the AIR service. The function handles end-to-end flows, including UI presentation and cryptographic verification, streamlining integration with your decentralized app (dApp).

Install the AIR Kit

# Using npm
npm install @mocanetwork/airkit

Initialize the AIR Service

Before issuing a credential, you must initialize the AirService instance and pass in your partner ID and environment configuration.

<CredentialIssuance
  airService={airService}
  isLoggedIn={isLoggedIn}
  partnerId={partnerId}
  environmentConfig={environmentConfig}
/>

• airService – the initialized AIR SDK instance
• isLoggedIn – indicates whether the user is logged in with their AIR account
• partnerId – unique identifier for your integration partner account from the Developer Dashboard *environmentConfig – contains API URLs, widget URLs, locale, and theme

Generate the Authentication JWT

Issuance requires an auth token (JWT) to authenticate your service with AIR.

const jwt = await generateJwt({ partnerId, privateKey });

• generateJwt is a utility function. Refer to Authentication (Partner JWT) on how to generate JWT tokens
• partnerId and privateKey come from environment variables
• JWT is used for authorization when calling airService.issueCredential function

NOTE: For production, generate JWTs on the backend to keep private keys secure.

Configure Issuance Parameters

Set up the essential credential issuance details

const config = {
  issuerDid: "did:example:issuer123",
  credentialId: "c21hc0g0joevn0015479aK"
};

• issuerDid** – Decentralized Identifier of the issuer
• credentialId – Program ID for the credential created on the Developer Dashboard

Define the Credential Subject

The credential subject contains the data fields issued to the user, e.g., age, location, or email.

const credentialSubject = {
  age: 20,
  location: "Netherlands",
  isMember: true
};

• Fields can be string, number, boolean, or date.
• The schema for the credential is defined before creating the Issuance program ID on the Developer Dashboard.

Issue the Credential

Call the AIR service to issue the credential:

await airService.issueCredential({
  authToken: jwt,
  credentialId: config.credentialId,
  credentialSubject: credentialSubject,
  issuerDid: config.issuerDid
});

• authToken – JWT generated in step 2
• credentialId – ID of the credential program
• credentialSubject – JSON object of the data to populate for the credential
• issuerDid – DID of the issuer

On success, the user receives a signed credential that can be stored in their wallet or identity provider.

Handle Issuance Status

The component tracks status for better UX:

• Loading – Shows a spinner while issuing the credential
• Success – Displays a success message when the credential is issued
• Error – Shows any errors if issuance fails

setIsLoading(true);
setIsSuccess(true);
setError(null);

Summary of Issuance Process:

1. Initialize AirService with environment config and partner ID
2. Generate a JWT for authentication
3. Configure issuer DID and issuance program ID on the Developer Dashboard
4. Add credential subject fields (dynamic data)
5. Call airService.issueCredential to issue the credential
6. Handle success or error states

Example Implementation

For a complete working example, check out the AIR Credential Example repository which demonstrates:

• Full credential issuance flow with React components
• Dynamic credential subject field management
• Error handling and status management
• Complete integration with the AIR Kit's Credential Services

Next Steps

Now that you know how to issue credentials, you can:

• Verify credentials - Learn how to verify the credentials you've issued in the Credential Verification Quickstart