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
| Property | Type | Required | Default | Description |
|---|---|---|---|---|
baseUrl | String | Yes | – | Public URL where the issuer service is reachable. |
ciTokenKey | String | No | Generated secp256r1 JWK | Serialized key used to sign/verify OAuth2 access & refresh tokens. |
signedMetadata | Object | No | Token-signing key | Selects an inline JWK, inline PEM key and certificates, or an injected key reference for metadata signing. |
credentialEncryptionKey | String | No | Not set | Serialized EC P-256 private key used for OID4VCI Credential Request decryption and Credential Response encryption. |
enforcePushedAuthorizationRequests | Boolean | No | false | Require clients to use the Pushed Authorization Request (PAR) endpoint. |
batchCredentialIssuance.batchSize | Integer | No | Not set | Maximum 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-knownmetadata, 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 privatejwkobject. Publishes the publicjwk.x509-chain: an inline unencrypted PKCS#8privateKeyPemand a required, non-emptycertificateChainPemarray. Publishesx5c.key-reference: areferenceresolved by an injected key resolver, with optionalx5cReferencesresolved by an injected certificate resolver. Publishesx5cwhen a certificate chain is resolved; otherwise publishes the publicjwk.
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".
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:
baseUrlpoints to your public HTTPS URL.ciTokenKeyis set to a securely generated, persistent key (consider a KMS backend such asaws-rest-api,azure-rest-apiortserather than an inline JWK).- If encrypted Credential Requests or encrypted Credential Responses are required, set
credentialEncryptionKeyto 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
Related Configuration
These concerns are configured in their own files, not in issuer-service.conf:
- Credential Issuer Metadata – OID4VCI metadata configuration (
credential-issuer-metadata.conf) - Issuer Profiles – Credential profiles, including issuer signing keys and DIDs (
issuer2-profiles.conf)
