Issuer Service Configuration

The issuer-service.conf file configures core Issuer2 service settings: the service's public URL, the key used to sign OAuth2 tokens, optional metadata signing and credential encryption support, the Pushed Authorization Request (PAR) policy, and OpenID4VCI Credential Endpoint batch issuance.

signedMetadata also signs OAuth authorization server metadata; signing is disabled when unconfigured.

File Location

waltid-services/waltid-issuer-api2/config/issuer-service.conf

Configuration Options

PropertyTypeRequiredDefaultDescription
baseUrlStringYes–Public URL where the issuer service is reachable.
ciTokenKeyStringNoGenerated secp256r1 JWKSerialized key used to sign/verify OAuth2 access & refresh tokens.
signedMetadataObjectNoToken-signing keySelects an inline JWK, inline PEM key and certificates, or an injected key reference for metadata signing.
credentialEncryptionKeyStringNoNot setSerialized EC P-256 private key used for OID4VCI Credential Request decryption and Credential Response encryption.
enforcePushedAuthorizationRequestsBooleanNofalseRequire clients to use the Pushed Authorization Request (PAR) endpoint.
batchCredentialIssuance.batchSizeIntegerNoNot setMaximum number of holder proofs (proofs.jwt) accepted on one Credential Request. Must be 2 or greater when set. Advertised as batch_credential_issuance.batch_size in issuer metadata.

baseUrl

The public URL where the issuer service is accessible. Every OID4VCI endpoint is derived from it:

  • The credential issuer base and metadata URLs become "<baseUrl>/openid4vci". This is what is written into credential offers and the .well-known metadata, so it must be the URL wallets can actually reach.
  • The external OAuth callback becomes "<baseUrl>/openid4vci/external/oauth/callback".

Trailing slashes are trimmed automatically.

baseUrl = "http://localhost:7005"

When running via Docker Compose, environment interpolation is supported:

baseUrl = "http://${SERVICE_HOST}:${ISSUER_API2_PORT}"

ciTokenKey

The key used to sign and verify the OAuth2 access tokens and refresh tokens issued by the service's token endpoint.

The value is a serialized walt.id key — the same format used elsewhere in walt.id — provided as a single JSON string. The type field selects the key backend and is required; omitting it causes startup to fail. Because the value is a string (not a HOCON object), use a triple-quoted HOCON string so the inner quotes do not need escaping:

ciTokenKey = """{"type":"jwk","jwk":{"kty":"EC","d":"...","crv":"P-256","x":"...","y":"..."}}"""

Supported type values include jwk (local key), tse (HashiCorp Vault Transit), aws-rest-api (AWS KMS), azure-rest-api (Azure Key Vault) and oci-rest-api (Oracle Cloud KMS).

Generating a key

The simplest way to get a stable local JWK in exactly the format above is a one-line Node.js command. It is identical on macOS, Linux, and Windows (PowerShell or cmd):

node -e "const{generateKeyPairSync}=require('crypto');const{privateKey}=generateKeyPairSync('ec',{namedCurve:'P-256'});const q=String.fromCharCode(34).repeat(3);console.log('ciTokenKey = '+q+JSON.stringify({type:'jwk',jwk:privateKey.export({format:'jwk'})})+q)"

It prints the complete config line — triple-quoted and ready to paste straight into issuer-service.conf, for example:

ciTokenKey = """{"type":"jwk","jwk":{"kty":"EC","x":"...","y":"...","crv":"P-256","d":"..."}}"""

Generate your own — never reuse the example value from these docs.

If you don't have Node installed, you can instead simply omit ciTokenKey: the service generates a key automatically on startup. Note the limitation described below.

If omitted, a new secp256r1 JWK is generated on every startup. This is fine for local development, but not for production: the signing key changes on each restart, so any tokens issued before a restart can no longer be verified. Always set ciTokenKey explicitly in real deployments.

signedMetadata

Object (optional) — Selects the key used to sign Credential Issuer Metadata. When omitted, Issuer2 uses its existing token-signing key and publishes its public jwk.

Set signingMethod.type to one of:

  • static-jwk: an inline private jwk object. Publishes the public jwk.
  • x509-chain: an inline unencrypted PKCS#8 privateKeyPem and a required, non-empty certificateChainPem array. Publishes x5c.
  • key-reference: a reference resolved by an injected key resolver, with optional x5cReferences resolved by an injected certificate resolver. Publishes x5c when a certificate chain is resolved; otherwise publishes the public jwk.

Choose one of these configurations and replace the placeholders with your key material.

Inline Private JWK

signedMetadata {
  signingMethod {
    type = "static-jwk"
    jwk = {
      kty = "EC"
      crv = "P-256"
      x = "{publicX}"
      y = "{publicY}"
      d = "{privateD}"
    }
  }
}

Inline PEM Key and Certificates

signedMetadata {
  signingMethod {
    type = "x509-chain"
    privateKeyPem = """
-----BEGIN PRIVATE KEY-----
{privateKeyBase64}
-----END PRIVATE KEY-----
"""
    certificateChainPem = ["""
-----BEGIN CERTIFICATE-----
{leafCertificateBase64}
-----END CERTIFICATE-----
"""]
  }
}

Injected Key Reference

signedMetadata {
  signingMethod {
    type = "key-reference"
    reference = "metadata-signing-key"
    x5cReferences = ["metadata-signing-certificate"] # Optional, leaf first
  }
}

key-reference requires a MetadataSigningKeyReferenceResolver injected into the service. When x5cReferences is configured, also inject a MetadataSigningCertificateReferenceResolver that returns one PEM certificate per reference. The resolvers define what the references mean; Enterprise KMS and X.509 Store IDs do not work automatically in standalone OSS.

x5cReferences is optional and overrides any certificate chain returned by the key resolver. When omitted, Issuer2 uses that resolver-provided chain if available; otherwise it publishes the public jwk. Empty arrays, blank references, and unresolved key or certificate references are rejected.

For inline x509-chain, provide one PEM certificate per certificateChainPem entry. For key-reference, list certificate references in x5cReferences. Both use leaf-first order, followed by any intermediates. The private key must match the leaf certificate. Issuer2 validates certificate dates, chain consistency, and signing usage. Certificate mode publishes standard Base64 DER certificates in x5c and omits jwk. The wallet applies its own certificate trust policy.

Issuer2 selects a compatible signing algorithm from the key. The JWK's alg is optional; when present, it must be compatible with the key. Metadata signing does not change token signing, credential signing, or encryption settings.

Restart the service after changing signedMetadata. Invalid signing material prevents initialization; Issuer2 does not fall back to the token key after a configuration error.

Request the signed response with Accept: application/jwt. Use application/json for ordinary JSON metadata. The following example uses baseUrl = "http://localhost:7005".

CURL

Endpoint: GET /.well-known/openid-credential-issuer/openid4vci | API Reference

Example Request
curl -X 'GET' \
  'http://localhost:7005/.well-known/openid-credential-issuer/openid4vci' \
  -H 'Accept: application/jwt'

Example Response
{protectedHeader}.{payload}.{signature}

Returns 200 with Content-Type: application/jwt. The payload contains the current Credential Issuer Metadata plus iss, sub, and iat.

credentialEncryptionKey

credentialEncryptionKey enables OID4VCI Credential Request encryption and Credential Response encryption.

Issuer2 supports this profile:

  • Key type: EC P-256
  • JWE alg: ECDH-ES
  • JWE enc: A128GCM
  • Compression: not supported

When configured, issuer metadata includes credential_request_encryption and credential_response_encryption with encryption_required = false.

Wallets can keep using normal JSON credential requests while encryption_required is false. The walt.id wallet uses the advertised profile automatically: it sends the Credential Request as application/jwt and stores the decrypted Credential Response. A Deferred Credential Request is encrypted the same way when that profile is advertised, with its own credential_response_encryption. Other wallets that send an encrypted Credential Request as application/jwt and include credential_response_encryption receive the Credential Response as an encrypted JWE.

Use a dedicated key for credential encryption. Do not reuse the token signing key or credential signing keys.

credentialEncryptionKey = """{"type":"jwk","jwk":{"kty":"EC","crv":"P-256","x":"...","y":"...","d":"..."}}"""

enforcePushedAuthorizationRequests

Controls the OAuth2 Pushed Authorization Request (PAR, RFC 9126) policy for the authorization code flow. Defaults to false.

Set enforcePushedAuthorizationRequests to true in issuer-service.conf to require Pushed Authorization Requests (PAR) for the authorization code flow:

enforcePushedAuthorizationRequests = true

Wallets must POST the authorization parameters to /openid4vci/par, then open /openid4vci/authorize with their client_id and the returned request_uri. Direct authorization requests are rejected with invalid_request.

The default is false, which allows both direct authorization and PAR. Authorization server metadata exposes the setting as require_pushed_authorization_requests.

keyAttestationConfig

Configure trusted key-attestation signers through keyAttestationConfig in issuer-service.conf. Provide the attester's public JWK or trusted X.509 CA certificates.

This configuration verifies both key attestations included in JWT proofs and standalone attestation proofs. OAuth client-attestation trust is configured separately through clientAuthenticationConfig. Signed challenges on that attestation are client attestation challenges.

See proof configuration and the Swagger examples for complete configurations.

batchCredentialIssuance

Optional OpenID4VCI 1.0 Credential Endpoint batch: the wallet sends several holder proofs in proofs.jwt and receives one credential per proof. This is not the draft-13 /batch_credential endpoint, and it is not the same as a multi-credential offer (credentials[] on create-offer).

When set, batchSize must be an integer >= 2. The shipped sample config uses 10. Omit the block to reject proofs with invalid_credential_request. A request whose proof count exceeds batchSize is also rejected with invalid_credential_request.

batchCredentialIssuance {
    batchSize = 10
}

Each proof issues a copy of the selected offer item. If that item includes credentialStatus, Issuer2 embeds the same status entry on every copy. To issue the same profile twice with different status entries, put two items in credentials[] and have the wallet use authorization_details plus credential_identifier.

Example Configuration

# issuer-service.conf

baseUrl = "http://localhost:7005"

# Optional: provide a stable token signing key (recommended for anything beyond local dev)
ciTokenKey = """{"type":"jwk","jwk":{"kty":"EC","d":"...","crv":"P-256","x":"...","y":"..."}}"""

# Optional: enable OID4VCI Credential Request/Response encryption
credentialEncryptionKey = """{"type":"jwk","jwk":{"kty":"EC","crv":"P-256","x":"...","y":"...","d":"..."}}"""

# Optional: require Pushed Authorization Requests
enforcePushedAuthorizationRequests = false

# Optional: allow several holder proofs on one Credential Request
batchCredentialIssuance {
    batchSize = 10
}

Production Configuration

For production deployments, ensure:

  1. baseUrl points to your public HTTPS URL.
  2. ciTokenKey is set to a securely generated, persistent key (consider a KMS backend such as aws-rest-api, azure-rest-api or tse rather than an inline JWK).
  3. If encrypted Credential Requests or encrypted Credential Responses are required, set credentialEncryptionKey to a dedicated EC P-256 private key.
# Production example
baseUrl = "https://issuer.example.com"
ciTokenKey = """{"type":"jwk","jwk":{"kty":"EC","d":"...","crv":"P-256","x":"...","y":"..."}}"""
credentialEncryptionKey = """{"type":"jwk","jwk":{"kty":"EC","crv":"P-256","x":"...","y":"...","d":"..."}}"""
enforcePushedAuthorizationRequests = true

These concerns are configured in their own files, not in issuer-service.conf:

Last updated on November 10, 2026