Issuer Configuration Reference

Every setting the credential issuance service accepts. A minimal configuration with only the required settings is in Install the issuance service.

server.json

{
  "port": 8079, // (1)!
  "baseUrl": "http://localhost:8079", // (2)!
  "database": { // (3)!
    "persistenceUnitName": "model",
    "driver": "org.postgresql.Driver",
    "url": "jdbc:postgresql://postgres:5432/issuer",
    "user": "postgres",
    "password": "postgres"
  },
  "issuer": { // (4)!
    "id": "issuer.example.org",
    "display": {
      "name": "Example University",
      "logoFile": "conf/static/logo.png"
    }
  },
  "signing": { // (5)!
    "keyFile": "conf/signing-key/issuer.key",
    "certificateFiles": [
      "conf/signing-key/issuer.pem",
      "conf/signing-key/intermediate.pem"
    ]
  },
  "integrations": { // (6)!
    "authentication": {
      "veUpCKs6U62JYBy9n7v8ZKZUYDIeBCXQ1A8hlR57p4cLKayiAd9nKfI9NXuE9Fna": "Calling application name"
    }
  },
  "authorizationServer": { // (7)!
    "baseUrl": "https://auth.example.org"
  },
  "sessionCallback": { // (8)!
    "targetUrl": "https://example-application.com/issued-credential",
    "bearerToken": "<a secret your application checks>"
  },
  "credentialOfferPrefix": "haip-vci://", // (9)!
  "statusListTtl": 600 // (10)!
}

1. Required. REST endpoint port.
2. Required. The address this service advertises to wallets. The wallet uses it to fetch the credential offer, the issuer metadata and the credential itself, so it must be reachable by the wallet — see Going to production.
3. Required. PostgreSQL connection. See Database.
4. Required. Information about the issuer. id is required and becomes the iss claim of every credential issued — a plain identifier string, not a key or an address. The optional display block is described in Issuer display.
5. Required. Signing key and certificate chain, leaf first. Emitted as the x5c header of every credential. See Signing certificates.
6. Required. API keys for the administrative endpoints. The JSON key is the token, the value a label. See API keys.
7. Optional. An external OAuth 2.0 authorization server. Omit it and the issuance service acts as the authorization server itself. Setting it changes how issuances start — see OAuth 2.0 integration.
8. Optional. Where a copy of each issued credential is pushed. See Receive the issued credential.
9. Optional. The scheme of the credential offer deep link handed to wallets. Defaults to haip-vci://. Change it only to match a wallet that registers a different scheme. The verifier has an equivalent, uri_prefix, set per verification query and defaulting to haip-vp://.
10. Optional. How long, in seconds, a published status list token stays valid. Defaults to 600. See Revocation.

Issuer display

These values give a wallet something meaningful to show alongside the credentials you issue, instead of a bare identifier. The whole block is optional.

"display": {
  "name": "Example University", // (1)!
  "logoFile": "conf/static/logo.png" // (2)!
}

1. Optional. An issuer-level display name a wallet may show alongside credentials.
2. Optional. Path to an image file inside the container, included in credential metadata for wallets to fetch.

The verifier has an equivalent block, clientMetadata, shown to the holder on the consent screen. See Client metadata.

Paths are relative to the container

keyFile, certificateFiles and logoFile are resolved against the container's working directory, /app. Mount your configuration directory there — ./issuer/conf:/app/conf:ro — so conf/signing-key/issuer.key refers to issuer/conf/signing-key/issuer.key on the host.

A misspelled setting stops the service

An unrecognized key fails startup and is named in the error, so a typo surfaces immediately rather than silently doing nothing.