> ## Documentation Index
> Fetch the complete documentation index at: https://www.agentcommercekit.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Credential Issuer Example

> An example of how to operate a Verifiable Credential Issuer.

## Overview

This example demonstrates an [ACK-ID](https://agentcommercekit.com/ack-id) and [ACK-Pay](https://agentcommercekit.com/ack-pay) Verifiable Credential issuer API built with [Hono](https://hono.dev).

The API supports issuing, verifying, and revoking two primary credential types:

* **`ControllerCredential`**: proves ownership of DIDs (part of ACK-ID).
* **`PaymentReceiptCredential`**: provides proof of payment meeting a Payment Request (part of ACK-Pay).

The issuer implements credential revocation using [Bitstring Status List](https://www.w3.org/TR/vc-bitstring-status-list/), a privacy-preserving and efficient revocation list method.

## Installation and Setup

Install dependencies and prepare your environment.

From within the issuer example directory (e.g., from project root: `./examples/issuer`) execute the setup:

```sh theme={null}
pnpm run setup
```

## Running the Server

Start the API server locally:

```sh theme={null}
pnpm run dev
```

The server runs at: [http://localhost:3456](http://localhost:3456)

## API Endpoints

### Authentication

All endpoints require a **signed payload** (JWT) proving DID ownership. During local development, include the `X-Payload-Issuer` header with a resolvable DID-URI to bypass signature verification.

### Response Format

All API responses use this JSON structure:

```json theme={null}
{
  "ok": true,
  "data": <data>
}
```

or

```json theme={null}
{
  "ok": false,
  "error": "Error message"
}
```

### Controller Credential Endpoints

#### `POST /credentials/controller`

Issue a ControllerCredential proving DID control.

**Sample cURL:**

```sh theme={null}
curl --request POST \
  --url http://localhost:3456/credentials/controller \
  --header 'Content-Type: application/json' \
  --header 'X-Payload-Issuer: did:web:0.0.0.0%3A3458:controller' \
  --data '{
  "controller": "did:web:0.0.0.0%3A3458:controller",
  "subject": "did:web:0.0.0.0%3A3458:agent"
}'
```

#### `GET /credentials/controller/:id`

Retrieve a ControllerCredential by ID.

**Sample cURL:**

```sh theme={null}
curl --request GET \
  --url http://localhost:3456/credentials/controller/abc123
```

#### `DELETE /credentials/controller`

Revoke a ControllerCredential by ID.

**Sample cURL:**

```sh theme={null}
curl --request DELETE \
  --url http://localhost:3456/credentials/controller \
  --header 'Content-Type: application/json' \
  --header 'X-Payload-Issuer: did:web:0.0.0.0%3A3458:controller' \
  --data '{
  "id": "abc123"
}'
```

### Payment Receipt Endpoints

#### `POST /credentials/receipts`

Issue a PaymentReceiptCredential.

**Sample cURL:**

```sh theme={null}
curl --request POST \
  --url http://localhost:3456/credentials/receipts \
  --header 'Content-Type: application/json' \
  --header 'X-Payload-Issuer: did:web:0.0.0.0%3A3458:wallet' \
  --data '{
  "metadata": { "txHash": "0x123abc456def" },
  "payerDid": "did:web:0.0.0.0%3A3458:wallet",
  "paymentRequestToken": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9...",
  "paymentOptionId": "option1"
}'
```

#### `GET /credentials/receipts/:id`

Retrieve a PaymentReceiptCredential by ID.

**Sample cURL:**

```sh theme={null}
curl --request GET \
  --url http://localhost:3456/credentials/receipts/abc123
```

#### `DELETE /credentials/receipts`

Revoke a PaymentReceiptCredential by ID.

**Sample cURL:**

```sh theme={null}
curl --request DELETE \
  --url http://localhost:3456/credentials/receipts \
  --header 'Content-Type: application/json' \
  --header 'X-Payload-Issuer: did:web:0.0.0.0%3A3458:payee' \
  --data '{
  "id": "abc123"
}'
```

### Status List Endpoint

#### `GET /status/:listId`

Retrieve Bitstring Status List credential for revocation checks.

**Sample cURL:**

```sh theme={null}
curl --request GET \
  --url http://localhost:3456/status/1
```

### DID Document Endpoint

#### `GET /.well-known/did.json`

Retrieve the issuer's DID Document.

**Sample cURL:**

```sh theme={null}
curl --request GET \
  --url http://localhost:3456/.well-known/did.json
```

## References

* [Verifiable Credentials Data Model Specification](https://www.w3.org/TR/vc-data-model/)
* [This Example's Source Code](https://github.com/agentcommercekit/ack/tree/main/examples/issuer)