Next.js

Use @authbound/server from a Next.js App Router server route or server action to create credential definitions and OpenID4VCI wallet offers. The SDK speaks to the public API at https://api.authbound.io using your secret key.

Issuance always runs on the server. Never create offers or definitions from a client component, route handler that runs on the edge with browser env vars, or any code that ships your secret key to the browser.

Install

pnpm add @authbound/server

Environment

.env.local

AUTHBOUND_SECRET_KEY=sk_test_...
AUTHBOUND_API_URL=https://api.authbound.io

Initialize once

Create a small server-only module so the client is reused across requests.

lib/authbound.ts

import "server-only";

import { AuthboundClient } from "@authbound/server";

if (!process.env.AUTHBOUND_SECRET_KEY) {
  throw new Error("AUTHBOUND_SECRET_KEY is required");
}

export const authbound = new AuthboundClient({
  apiKey: process.env.AUTHBOUND_SECRET_KEY,
  apiUrl: process.env.AUTHBOUND_API_URL,
});

Ensure a credential definition exists

Definitions are project-scoped templates. Create them once at boot or lazily when an offer is requested. The pattern below tries to load the definition first and creates it only when missing.

lib/credential-definitions.ts

import "server-only";

import { AuthboundClientError } from "@authbound/server";

import { authbound } from "@/lib/authbound";

const credentialDefinitionId = "pension_credential_v1";

export async function ensurePensionDefinition() {
  try {
    return await authbound.issuer.credentialDefinitions.get(
      credentialDefinitionId
    );
  } catch (error) {
    if (
      !(error instanceof AuthboundClientError) ||
      error.code !== "credential_definition_not_found"
    ) {
      throw error;
    }
  }

  return authbound.issuer.credentialDefinitions.create({
    credentialDefinitionId,
    vct: "urn:vc:authbound:pension:1.0",
    format: "dc+sd-jwt",
    title: "Pension Credential",
    aliases: ["pension"],
    claims: [
      { path: ["Person", "given_name"], mandatory: true, displayName: "Given Name" },
      { path: ["Person", "family_name"], mandatory: true, displayName: "Family Name" },
      { path: ["Pension", "startDate"], mandatory: true, displayName: "Start Date" },
    ],
  });
}

If two processes run this helper at the same time, the slower create fails with HTTP 409 and code credential_definition_conflict. Catch that and call get again.

Create an offer with a Server Action

The simplest way to hand a wallet offer to the user from an App Router page is a server action that returns the public fields the browser needs.

app/issue/pension/actions.ts

"use server";

import { authbound } from "@/lib/authbound";
import { ensurePensionDefinition } from "@/lib/credential-definitions";

export async function createPensionOffer(input: {
  userId: string;
  givenName: string;
  familyName: string;
  startDate: string;
}) {
  const definition = await ensurePensionDefinition();

  const offer = await authbound.openId4Vc.issuance.createOffer({
    credentialDefinitionId: definition.credentialDefinitionId,
    claims: {
      Person: {
        given_name: input.givenName,
        family_name: input.familyName,
      },
      Pension: {
        startDate: input.startDate,
      },
    },
    issuanceMode: "InTime",
    metadata: {
      userId: input.userId,
    },
    idempotencyKey: `pension:${input.userId}:${input.startDate}`,
  });

  return {
    issuanceId: offer.id,
    offerUri: offer.offerUri,
    offerQrUri: offer.offerQrUri,
    expiresAt: offer.expiresAt,
  };
}

Render the wallet handoff

app/issue/pension/page.tsx

import { createPensionOffer } from "./actions";

export default async function PensionIssuancePage() {
  const offer = await createPensionOffer({
    userId: "user_123",
    givenName: "Sergio",
    familyName: "Jack",
    startDate: "2025-01-01",
  });

  return (
    <main>
      <h1>Pension credential</h1>
      <p>Open this offer in your wallet to receive the credential.</p>
      <a href={offer.offerUri}>Open in wallet</a>
      <pre>{offer.offerQrUri}</pre>
    </main>
  );
}

For desktop, encode offer.offerQrUri as a QR code image. For mobile, render offer.offerUri as a tappable link.

What you just received

The result of createOffer is not a credential. It is a wallet handoff for an OpenID4VCI flow:

Field	Meaning
`id`	Issuance session ID. Use this to poll status or cancel.
`status`	Lifecycle state. Starts at `offer_created`.
`offerUri`	Mobile wallet link.
`offerQrUri`	URI to render as a QR code.
`credentialIssuer`	Authbound issuer base URL the wallet connects to.
`expiresAt`	When the offer becomes unredeemable.

The wallet receives the credential only after it redeems the offer with the issuer.

Track issuance status

const latest = await authbound.openId4Vc.issuance.get(offer.id);

if (latest.status === "credential_issued") {
  // Mark the user as having claimed the credential in your own database.
}

For deferred issuance and patching claims after the offer is created, see Deferred issuance.

Credential definitions

Define the credential type and claim paths your business will issue.

Credential offers

Lifecycle, transaction codes, cancellation, and status polling.

Troubleshooting

Fix credential_definition_not_found, invalid_key_format, and other common errors.

Start here

Identity verification

Credential issuance

AI

Install

Environment

Initialize once

Ensure a credential definition exists

Create an offer with a Server Action

Render the wallet handoff

What you just received

Track issuance status

Next

Credential definitions

Credential offers

Troubleshooting

​Install

​Environment

​Initialize once

​Ensure a credential definition exists

​Create an offer with a Server Action

​Render the wallet handoff

​What you just received

​Track issuance status

​Next

Credential definitions

Credential offers

Troubleshooting

Install

Environment

Initialize once

Ensure a credential definition exists

Create an offer with a Server Action

Render the wallet handoff

What you just received

Track issuance status

Next