Quickstart 2: Credential issuance

This guide implements interactive credential issuance from end to end. Your web app starts the flow with AIR Kit, AIR resolves the holder, and your issuer backend creates, signs, encrypts, and stores the credential. New issuance programs should use the BJJ_SIG_2021 proof type.

This guide covers user-initiated issuance through a hosted issuer backend. To issue from a script or backend job without a user session, use Direct Issuance.

Before you start

You need:

Node.js 18 or later
A database
An AIR Developer Dashboard account and Partner ID
The hosted AIR issuer service starter supplied during issuer onboarding
Two public HTTPS origins, or HTTPS tunnels, for your issuer backend and web app
Contact to the AIR team for issuer activation and backend whitelisting

Critical setup checkpoints

These requirements block successful issuance if skipped:

Set the issuer seed first. Replace the SEED placeholder before generating the issuer DID. Changing the seed later produces a different DID.
Complete AIR activation. AIR must register your Issuer DID, API key, Partner ID, and issuer endpoint URLs before the Credential API will call your backend.
Publish and register your JWKS. Host it at a public HTTPS URL, register the exact URL in the Developer Dashboard, and sign Partner JWTs with a matching kid. See JWKS endpoint setup.

What you will build

By the end of this guide, you will have:

A public issuer backend with POST /available-vc, POST /issue-vc, and credential-status endpoints
An issuer DID derived from a secret seed
A Dashboard schema and issuance program
A schema class that produces the claims your backend signs
A public JWKS endpoint and a server-only Partner JWT endpoint
A web flow that logs in with AIR Kit and calls issueCredential

The public examples below are useful implementation companions, but the steps on this page contain the required integration contract:

Credential issuance service

A production-oriented AIR issuer backend.

AIR E2E Example

A monorepo that includes both the backend and frontend implementations, showcasing the complete end-to-end integration as a single, cohesive example.

How hosted issuance works

The browser never calls /available-vc or /issue-vc directly. AIR calls these endpoints with x-api-key and supplies the holder DID, encryption public key, and partner user ID. The issuance program ID is an AIR Kit and Dashboard identifier. Your issuer backend receives a schemaId, not the program ID.

Step 1: Generate issuer and partner secrets

Generate a 32-byte issuer seed and separate API keys:

echo "SEED=0x$(openssl rand -hex 32)"
echo "API_KEY=$(openssl rand -hex 32)"
echo "ADMIN_API_KEY=$(openssl rand -hex 32)"

SEED deterministically controls your issuer DID. Store it in a secret manager, back it up, and do not rotate it for an existing issuer. Generate an RSA key pair for Partner JWT signing:

openssl genpkey \
  -algorithm RSA \
  -pkeyopt rsa_keygen_bits:2048 \
  -out partner-private.pem

openssl pkey \
  -in partner-private.pem \
  -pubout \
  -out partner-public.pem

You will use the same key pair in two places:

The issuer backend signs requests to DStorage with the private key.
Your web server signs short-lived AIR Kit Partner JWTs with the private key and exposes the public key through JWKS.

Never expose the private key or issuer seed through a NEXT_PUBLIC_* environment variable.

Step 2: Configure and start the issuer backend

Create the issuer backend environment file:

# PostgreSQL
DATABASE_URL=postgres://postgres:postgres@127.0.0.1:5432/issuer-backend

# Public origin of this issuer service, without a trailing slash
ISSUER_ORIGIN=https://issuer.example.com

# AIR and Moca Chain sandbox services
AIR_API_ORIGIN=https://air.api.sandbox.air3.com
MOCA_CHAIN_API_ORIGIN=https://api.sandbox.mocachain.org

# Issuer identity
SEED=0x<64-hex-characters>
IDEN3_METHOD=air
IDEN3_BLOCKCHAIN=id
IDEN3_NETWORK_ID=testnet

# Partner identity and signing
PARTNER_ID=<dashboard-partner-id>
PARTNER_PRIVATE_KEY_KID=<dashboard-partner-id>
PARTNER_PRIVATE_KEY_ALG=RS256
PARTNER_PRIVATE_KEY_DER=<pkcs8-private-key-body-without-pem-markers>
SD_JWT_HASH_ALG=sha-256

# AIR-to-issuer and operator authentication
API_KEY=<generated-api-key>
ADMIN_API_KEY=<generated-admin-api-key>

# Optional
PORT=3000

PARTNER_PRIVATE_KEY_DER is the base64 body between the BEGIN PRIVATE KEY and END PRIVATE KEY lines in partner-private.pem. It must be PKCS#8. Install dependencies, apply the database migrations, and start the service: Check that the database, migrations, and issuer identity are ready:

curl -s http://localhost:3000/ready | jq .

A ready service returns HTTP 200:

{
  "status": "ready",
  "checks": {
    "database": { "status": "ok" },
    "migrations": { "status": "ok", "pending": [] },
    "issuer": { "status": "ok", "did": "did:air:..." }
  }
}

Retrieve the issuer DID:

curl -s http://localhost:3000/.well-known/issuer-did | jq .

The DID is derived from SEED and the three IDEN3_* values:

{
  "did": "did:air:...",
  "issuer": "https://issuer.example.com"
}

ISSUER_ORIGIN must be the public HTTPS origin that serves /credential-status/:nonce. This URL is embedded in every issued credential.

Step 3: Register the issuer with AIR

Expose the issuer backend over public HTTPS, then provide the Moca Network / AIR team with all four items:

Item	Value
Issuer DID	The `did` from `GET /.well-known/issuer-did`
API key	The backend `API_KEY`; AIR sends it as `x-api-key`
Partner ID	Your Dashboard Partner ID
Issuer endpoints	Full public URLs for `POST /available-vc` and `POST /issue-vc`

For example:

Issuer DID: did:air:...
Partner ID: 00000000-0000-0000-0000-000000000000
API key: <generated-api-key>
Available credentials: https://issuer.example.com/available-vc
Issue credential: https://issuer.example.com/issue-vc

After AIR activates the issuer:

Confirm the Issuer DID in the Dashboard matches GET /.well-known/issuer-did.
Confirm GET /ready returns "status": "ready" through the public URL.
Keep API_KEY identical to the value registered by AIR.

Until whitelisting is complete, AIR may not route requests to your backend, or the backend will return 403 because x-api-key is missing or incorrect.

Step 4: Create schema for credential issuance

After AIR activates your issuer, create the schema and issuance program:

Open the Sandbox Developer Dashboard.
Go to Issuer → Schemas.
Create a schema with a string attribute named historical_amount.
Publish the schema.
Record its schema ID, type, schema JSON URL, and JSON-LD context URL.
Go to Issuer → Programs and create an issuance program using the published schema.
Select BJJ_SIG_2021 as the signature type.
Record the issuance program ID.

For schema design rules and supported field types, see Schema creation.

Step 5: Implement the credential data

Create one schema class for each Dashboard schema. The class maps a Dashboard schema to the claims and expiration your backend will issue.

src/issuer/schemas/schema-<SCHEMA_ID>.ts

import { BaseSchema } from "./base-schema";

const EXPIRY_SEC = 30 * 24 * 60 * 60;

export default class HistoricalAmountSchema extends BaseSchema {
  public readonly schemaId = "<SCHEMA_ID>";
  public readonly schemaType = "<SCHEMA_TYPE>";
  public readonly schemaUrl = "<SCHEMA_JSON_URL>";
  public readonly schemaContextUrl = "<JSON_LD_CONTEXT_URL>";

  generateCredentialData() {
    return Promise.resolve({
      credentialSubject: {
        historical_amount: "1000",
      },
      expiration: Math.floor(Date.now() / 1000) + EXPIRY_SEC,
    });
  }
}

src/issuer/schemas/index.ts

import { BaseSchema } from "./base-schema";
import HistoricalAmountSchema from "./schema-<SCHEMA_ID>";

const schemas: BaseSchema[] = [new HistoricalAmountSchema()];

export default schemas;

Follow these rules:

Claim keys and JavaScript types must match the published Dashboard schema.
Return expiration as Unix time in seconds.
Do not add credentialSubject.id. The issuer service sets it to the holder DID after adding your claims.
Keep the backend authoritative. Do not sign claim values supplied by the browser without validating them against your own data.
When you replace the static example with a database or API lookup, use the AIR-resolved partner user ID at the issuer boundary for eligibility and data retrieval.

Setting credentialSubject.id to an email address or partner user ID causes schema validation to fail with must match format "uri". The holder DID must remain the credential subject ID.

Issuer endpoint contract

AIR calls the issuer endpoints. Your frontend does not call them. POST /available-vc accepts the AIR-resolved holder and optional filters:

{
  "holderDID": "did:air:...",
  "pubKey": "0x...",
  "userId": "<partner-primary-id>",
  "schemaId": "<optional-schema-id>",
  "proofType": "BJJ_SIG_2021"
}

It returns encrypted previews:

{
  "data": [
    {
      "holderDID": "did:air:...",
      "schemaId": "<SCHEMA_ID>",
      "credentialSubject": {
        "encryptedData": "...",
        "iv": "...",
        "authTag": "...",
        "dataEncPublicKey": "..."
      },
      "proofType": "BJJ_SIG_2021"
    }
  ]
}

POST /issue-vc accepts the selected schema:

{
  "holderDID": "did:air:...",
  "pubKey": "0x...",
  "userId": "<partner-primary-id>",
  "schemaId": "<SCHEMA_ID>",
  "proofType": "BJJ_SIG_2021"
}

On success, the issuer backend:

Generates the credential data.
Sets credentialSubject.id to holderDID.
Signs the W3C credential with the issuer identity derived from SEED.
Encrypts the complete credential to pubKey.
Persists the issuance record.
Uploads the encrypted credential to DStorage.
Returns HTTP 200 with an empty response body.

Both endpoints require x-api-key: <API_KEY>.

Step 6: Configure Partner authentication

Install AIR Kit in your web application:

pnpm add @mocanetwork/airkit

Add the browser-safe and server-only values to your web environment:

# Browser-safe
NEXT_PUBLIC_PARTNER_ID=<dashboard-partner-id>
NEXT_PUBLIC_ISSUER_DID=<issuer-did>
NEXT_PUBLIC_ISSUE_PROGRAM_ID=<dashboard-program-id>
NEXT_PUBLIC_BUILD_ENV=sandbox

# Server-only
PARTNER_PUBLIC_KEY=<public-key-body-without-pem-markers>
PARTNER_PRIVATE_KEY=<pkcs8-private-key-body-without-pem-markers>
SIGNING_ALGORITHM=RS256

Set up the JWKS endpoint

Complete JWKS endpoint setup, including deploying the endpoint at a public HTTPS URL and registering that exact URL in the Developer Dashboard. Before continuing, verify that the endpoint returns a keys array containing the kid your Partner JWT will use.

Sign the Partner JWT

Implement the Next.js Partner JWT endpoint. The endpoint must generate a short-lived token on the server with scope: "issue" and a kid that appears in your registered JWKS.

Step 7: Initialize AIR Kit and issue the credential

Create a singleton AIR service and a helper for fetching the Partner JWT:

lib/air.ts

import {
  AirService,
  BUILD_ENV,
  type BUILD_ENV_TYPE,
} from "@mocanetwork/airkit";

let airService: AirService | null = null;

function resolveBuildEnv(value?: string): BUILD_ENV_TYPE {
  const normalized = (value ?? "sandbox").toLowerCase();
  return (
    Object.values(BUILD_ENV).find(
      (environment) => environment === normalized,
    ) ?? BUILD_ENV.SANDBOX
  );
}

export async function getInitializedAirService(): Promise<AirService> {
  const partnerId = process.env.NEXT_PUBLIC_PARTNER_ID;
  if (!partnerId) throw new Error("NEXT_PUBLIC_PARTNER_ID is required");

  airService ??= new AirService({ partnerId });

  if (!airService.isInitialized) {
    await airService.init({
      buildEnv: resolveBuildEnv(process.env.NEXT_PUBLIC_BUILD_ENV),
      enableLogging: true,
      preloadCredential: true,
      preloadWallet: false,
      skipRehydration: false,
    } as Parameters<AirService["init"]>[0]);
  }

  return airService;
}

export async function fetchPartnerJwt(): Promise<string> {
  const response = await fetch("/api/partner-jwt", { method: "POST" });
  const body = (await response.json()) as {
    token?: string;
    error?: string;
  };

  if (!response.ok || !body.token) {
    throw new Error(
      body.error ?? `Partner JWT request failed (${response.status})`,
    );
  }

  return body.token;
}

import { fetchPartnerJwt, getInitializedAirService } from "@/lib/air";

export async function issueHistoricalAmountCredential() {
  const air = await getInitializedAirService();

  if (!air.isLoggedIn) {
    await air.login();
  }

  const authToken = await fetchPartnerJwt();

  return air.issueCredential({
    authToken,
    issuerDid: process.env.NEXT_PUBLIC_ISSUER_DID!,
    credentialId: process.env.NEXT_PUBLIC_ISSUE_PROGRAM_ID!,
    credentialSubject: {
      historical_amount: "1000",
    },
  });
}

For this hosted flow, credentialSubject is part of the SDK request, but it is not the signed source of truth. AIR calls your issuer backend, and the registered backend schema class supplies the claims that are signed into the credential.

Step 8: Complete Dashboard setup and test end to end

Complete the remaining Dashboard setup:

Add the web origin under Dashboard → Domains.
Confirm the Dashboard Issuer DID matches the backend DID.
Confirm the issuance program uses the same schema registered in the issuer backend.
Confirm AIR has whitelisted the backend API key and both issuer endpoint URLs.

Start the issuer backend and web app, then:

Open the web app.
Log in through AIR Kit.
Start credential issuance.
Confirm the AIR Credential UI shows the available credential.
Approve issuance.
Confirm the app receives a successful issueCredential result.

Check the backend issuance history:

curl -s \
  -H "x-admin-api-key: <ADMIN_API_KEY>" \
  "https://issuer.example.com/admin/issuance-history?page=1&limit=25" \
  | jq .

The backend’s /issue-vc response is intentionally empty. A successful issuance is delivered through AIR and DStorage rather than returned as a credential in that HTTP response.

Troubleshooting

Issuer backend returns 403

AIR is not sending the expected x-api-key, or the value differs from the backend API_KEY. Ask the Moca Network / AIR team to confirm the Partner ID, Issuer DID, API key, and endpoint whitelist.

AIR cannot validate the Partner JWT

Confirm:

The JWKS URL is public HTTPS and returns { "keys": [...] }.
JWT kid exactly matches a JWKS key.
JWT alg matches the JWKS alg.
The private and public keys belong to the same key pair.
The token contains scope: "issue" and has not expired.

See JWKS endpoint setup for a complete diagnostic checklist.

AIR does not call the issuer backend

Confirm the issuance program points to the activated Issuer DID and schema. Your web app shoudl not call your backend directly, so you will not see issuer requests until AIR routing and whitelisting are complete.

Overview

Early Access

Quick Setup

Flutter

Authentication

Quickstart Guides

Integration Guides

Credential Services

Account Services

Recipes

Plug & Play Templates

Tools & Config

Troubleshooting

Reference

Quickstart 2: Credential issuance

Before you start

Critical setup checkpoints

What you will build

Credential issuance service

AIR E2E Example

How hosted issuance works

Step 1: Generate issuer and partner secrets

Step 2: Configure and start the issuer backend

Step 3: Register the issuer with AIR

Step 4: Create schema for credential issuance

Step 5: Implement the credential data

Issuer endpoint contract

Step 6: Configure Partner authentication

Set up the JWKS endpoint

Sign the Partner JWT

Step 7: Initialize AIR Kit and issue the credential

Step 8: Complete Dashboard setup and test end to end

Troubleshooting

Issuer backend returns 403

AIR cannot validate the Partner JWT

AIR does not call the issuer backend

Schema validation fails

Issuer backend is unreachable

Next steps

​Before you start

​Critical setup checkpoints

​What you will build

Credential issuance service

AIR E2E Example

​How hosted issuance works

​Step 1: Generate issuer and partner secrets

​Step 2: Configure and start the issuer backend

​Step 3: Register the issuer with AIR

​Step 4: Create schema for credential issuance

​Step 5: Implement the credential data

​Issuer endpoint contract

​Step 6: Configure Partner authentication

​Set up the JWKS endpoint

​Sign the Partner JWT

​Step 7: Initialize AIR Kit and issue the credential

​Step 8: Complete Dashboard setup and test end to end

​Troubleshooting

​Issuer backend returns 403

​AIR cannot validate the Partner JWT

​AIR does not call the issuer backend

​Schema validation fails

​Issuer backend is unreachable

​Next steps

Before you start

Critical setup checkpoints

What you will build

How hosted issuance works

Step 1: Generate issuer and partner secrets

Step 2: Configure and start the issuer backend

Step 3: Register the issuer with AIR

Step 4: Create schema for credential issuance

Step 5: Implement the credential data

Issuer endpoint contract

Step 6: Configure Partner authentication

Set up the JWKS endpoint

Sign the Partner JWT

Step 7: Initialize AIR Kit and issue the credential

Step 8: Complete Dashboard setup and test end to end

Troubleshooting

Issuer backend returns 403

AIR cannot validate the Partner JWT

AIR does not call the issuer backend

Schema validation fails

Issuer backend is unreachable

Next steps