Issuing Credentials

What We Are Doing:

• Standing up a minimal Express server (src/index.js) that hosts our frontend and mounts an Issuer router.

• Implementing a route (/kyc-credential) that asks the Issuer to create a credential offer for our [email protected] schema, then returns the offer data and a QR code the user can scan.

Why: This page builds the backend that turns user input into a credential offer. We first need a working Express server, then a route that calls the Issuer's credential-offers endpoint. Scanning the returned QR code with the Empe DID Wallet starts an OpenID4VCI flow in which the wallet claims the credential from the Issuer. We create an offer, and the wallet pulls the credential using the pre-authorized code embedded in it — the Issuer never pushes credentials to a wallet.

Basic Express Server

What We Are Doing:

• Setting up a minimal Express application in src/index.js that:

  • Loads environment variables (via dotenv).

  • Serves static files from a public/ directory.

  • Mounts our Issuer router (where the /kyc-credential route will live).

Why: Before we can create any credential offers, we need a working Express server that can:

• Host our frontend assets (HTML/CSS/JS) under public/.

• Accept POST requests (JSON) from the frontend.

• Delegate route handling to src/issuer-routes.js.

• Spin up on a known port so the frontend and wallet can reach it.

Steps: Create src/index.js with the following contents:

import express from "express";
import path from "path";
import { fileURLToPath } from "url";
import dotenv from "dotenv";
import issuerRouter from "./issuer-routes.js";

dotenv.config();

// Convert module URL to a __dirname-like value
const __filename = fileURLToPath(import.meta.url);
const __dirname = path.dirname(__filename);

// PORT is the local tutorial app's own port (distinct from the deployed Issuer API).
// It comes from .env (fallback to 4000 if not set).
const PORT = process.env.PORT || 4000;

// Initialize Express app
const app = express();

// Serve static assets (index.html, scripts, styles) from public/
app.use(express.static(path.join(__dirname, "../public")));

// Mount our Issuer router (defined in src/issuer-routes.js)
app.use("/issuer", express.json(), issuerRouter);

// Start the server
app.listen(PORT, () => {
  console.log(`Server is running on http://localhost:${PORT}`);
});

Make sure your .env file holds the values we saved when deploying the Issuer and uploading the schema:

# Base URL of the deployed Issuer
ISSUER_BASE_URL=https://your-issuer.evdi.app

# Your Issuer's DID (read from the Issuer Details page)
ISSUER_DID=did:web:your-issuer.evdi.app:8f3c...

# Admin access token from the deployment's Keycloak, sent as: Authorization: Bearer <token>
ISSUER_ACCESS_TOKEN=your-oidc-access-token

# Port our local tutorial app listens on (its own port, not the deployed Issuer API's)
PORT=4000

These are accessible in code as process.env.ISSUER_BASE_URL, process.env.ISSUER_DID, and process.env.ISSUER_ACCESS_TOKEN.

Creating credential offers

With the server in place, we add a route (/kyc-credential) that:

• Takes user input (age, firstName, lastName).

• Asks the Issuer to create a credential offer for our [email protected] schema, with those values as the credential's claims.

• Returns the offer data, including a credentialOfferUri and a QR code the user can scan.

Issuance is a single, direct call: you POST straight to your Issuer's credential-offers route, referencing the credential configuration id you got from the schema ([email protected]:sd-jwt) and supplying the claim values through issuanceMetadata.

The credential-offers endpoint

POST {ISSUER_BASE_URL}/issuers/{issuerDid}/credential-offers

Creates a credential offer and an issuance session.

Request Body (application/json):

• credentialConfigurationIds (string array, required, at least one) — the credential configurations to offer, in name@version:format form, e.g. ["[email protected]:sd-jwt"].

• requirePin (boolean, optional, default false) — when true, the pre-authorized flow also requires a PIN, returned to you so you can hand it to the user out of band.

• issuanceMetadata (object, optional) — values passed to the credential mapper. Use claimsByConfigurationId to supply the actual claim values per configuration id.

Response Body:

• credentialOfferUri — an openid-credential-offer://... URI. This is what the wallet consumes (rendered as a QR code or opened as a deep link).

• issuanceSessionId — identifier of the issuance session you can poll to track progress.

• credentialConfigurationIds — the configurations included in the offer.

• userPin — present only when requirePin was true.

Example request body for our KYC credential:

{
  "credentialConfigurationIds": ["[email protected]:sd-jwt"],
  "issuanceMetadata": {
    "claimsByConfigurationId": {
      "[email protected]:sd-jwt": {
        "age": 30,
        "first_name": "Ada",
        "last_name": "Lovelace"
      }
    }
  }
}

Example response:

{
  "credentialOfferUri": "openid-credential-offer://?credential_offer=...",
  "issuanceSessionId": "d07d0df5-0d64-4f1a-9aa7-7e7f9c2a1d70",
  "credentialConfigurationIds": ["[email protected]:sd-jwt"]
}

Implementing the route

Steps: Update src/issuer-routes.js:

import { Router } from "express";
import dotenv from "dotenv";

dotenv.config();

const router = Router();
const ISSUER_BASE_URL = process.env.ISSUER_BASE_URL;
const ISSUER_DID = process.env.ISSUER_DID;
const ISSUER_ACCESS_TOKEN = process.env.ISSUER_ACCESS_TOKEN;

// The credential configuration id is "name@version:format".
// It comes from the schema we created and assigned earlier.
const CONFIG_ID = "[email protected]:sd-jwt";

router.post("/kyc-credential", async (req, res) => {
  try {
    const { age, firstName, lastName } = req.body;

    // Create a credential offer for our KYC credential.
    // The claim values are passed via issuanceMetadata.claimsByConfigurationId,
    // keyed by the same credential configuration id we are offering.
    const offerRes = await fetch(
      `${ISSUER_BASE_URL}/issuers/${ISSUER_DID}/credential-offers`,
      {
        method: "POST",
        headers: {
          "Content-Type": "application/json",
          Authorization: `Bearer ${ISSUER_ACCESS_TOKEN}`,
        },
        body: JSON.stringify({
          credentialConfigurationIds: [CONFIG_ID],
          issuanceMetadata: {
            claimsByConfigurationId: {
              [CONFIG_ID]: {
                age: Number(age),
                first_name: firstName,
                last_name: lastName,
              },
            },
          },
        }),
      }
    );

    if (!offerRes.ok) {
      const error = await offerRes.text();
      return res.status(offerRes.status).json({ error });
    }

    const offer = await offerRes.json();
    // offer.credentialOfferUri  -> openid-credential-offer://... (what the wallet reads)
    // offer.issuanceSessionId   -> use this to track the session status
    res.status(200).json({
      credentialOfferUri: offer.credentialOfferUri,
      issuanceSessionId: offer.issuanceSessionId,
      // Convenience: a URL our own server exposes that returns a QR PNG for the offer.
      qr_code_url: `/issuer/kyc-credential/${offer.issuanceSessionId}/qr-code`,
    });
  } catch (error) {
    console.error(error);
    res.status(500).json({ error: "Internal server error" });
  }
});

export default router;

Serving a QR code

The wallet needs to scan the credentialOfferUri. You can render it as a QR code yourself, or let the Issuer do it for you. The Issuer exposes two PNG endpoints:

• POST {ISSUER_BASE_URL}/issuers/{issuerDid}/credential-offers/qr-code — takes the same request body as the offer endpoint above, but responds with a 400 × 400 PNG image instead of JSON. The offer URI is returned in the X-Credential-Offer-Uri response header, the session id in X-Issuance-Session-Id, and (when a PIN is required) the PIN in X-Pin.

• GET {ISSUER_BASE_URL}/issuance-sessions/{sessionId}/qr-code — renders a PNG for an offer you already created, looked up by its session id. The offer URI is returned in the X-Credential-Offer-Uri header.

The second one pairs naturally with the route above: we already have the issuanceSessionId, so we can proxy its QR PNG straight to the browser. Add this handler to src/issuer-routes.js:

router.get("/kyc-credential/:sessionId/qr-code", async (req, res) => {
  try {
    const qrRes = await fetch(
      `${ISSUER_BASE_URL}/issuance-sessions/${req.params.sessionId}/qr-code`,
      { headers: { Authorization: `Bearer ${ISSUER_ACCESS_TOKEN}` } }
    );

    if (!qrRes.ok) {
      return res.status(qrRes.status).json({ error: await qrRes.text() });
    }

    // Stream the PNG back to the browser.
    res.set("Content-Type", "image/png");
    const buffer = Buffer.from(await qrRes.arrayBuffer());
    res.send(buffer);
  } catch (error) {
    console.error(error);
    res.status(500).json({ error: "Internal server error" });
  }
});

Requiring a PIN (optional)

For higher-assurance issuance, set requirePin: true in the offer body. The pre-authorized flow will then prompt the wallet for a PIN, and the response (or the X-Pin header on the QR endpoint) returns the userPin so you can deliver it to the user through a separate channel:

{
  "credentialConfigurationIds": ["[email protected]:sd-jwt"],
  "requirePin": true,
  "issuanceMetadata": {
    "claimsByConfigurationId": {
      "[email protected]:sd-jwt": { "age": 30, "first_name": "Ada", "last_name": "Lovelace" }
    }
  }
}

Tracking the issuance session

Each offer creates an issuance session you can inspect to see whether the wallet has claimed the credential:

• GET {ISSUER_BASE_URL}/issuance-sessions/{sessionId} — returns the session, including its state (for example OfferCreated while waiting, then Completed once the wallet claims it), credentialOfferUri, createdAt, expiresAt, and issuedCredentials when finished.

• GET {ISSUER_BASE_URL}/issuance-sessions?issuerId={issuerDid} — lists all sessions for your Issuer.

A quick check from the terminal:

curl "$ISSUER_BASE_URL/issuance-sessions/d07d0df5-0d64-4f1a-9aa7-7e7f9c2a1d70" \
  -H "Authorization: Bearer $ISSUER_ACCESS_TOKEN"

{
  "id": "d07d0df5-0d64-4f1a-9aa7-7e7f9c2a1d70",
  "issuerId": "did:web:your-issuer.evdi.app:8f3c...",
  "state": "OfferCreated",
  "credentialOfferUri": "openid-credential-offer://?credential_offer=...",
  "createdAt": "2026-06-22T12:00:00.000Z",
  "expiresAt": "2026-06-22T12:05:00.000Z"
}

Run the server

node src/index.js

Next, we will build a simple frontend form to submit the user data and display the QR code.