Verifier Service

verifier-service.conf configures the service-level defaults for the Verifier2 API — its identity as presented to wallets, the URLs used in authorization requests, and the optional signing key and certificate chain.

All fields in this file act as defaults. Every value can be overridden per-request in the request body when creating a verification session.

Fields

clientId

String — The identifier the verifier presents to wallets during the credential exchange.

The following formats are supported (defined in OID4VP 1.0, §5.9.3):

  • Plain string — e.g. "verifier2": used as-is in the authorization request. Suitable for development and use cases where the verifier does not need a verifiable identity.
  • x509_san_dns:<hostname> — e.g. "x509_san_dns:verifier.example.com": the client identity is bound to the DNS name in the certificate's Subject Alternative Name extension. Wallets verify the signed request against the SAN in the provided certificate. Use together with key and x5c.
  • x509_hash:<base64url-sha256-hash> — the client identity is bound to the SHA-256 hash of the DER-encoded leaf certificate. Wallets verify the signed request and check that the certificate matches the hash. Use together with key and x5c. Required by the HAIP profile.

Both x509_san_dns and x509_hash are general OID4VP client identifier schemes and can be used with any signed OID4VP request (cross-device, same-device, or DC API).

For unsigned DC API flows (signed_request: false), clientId is automatically omitted from the authorization request regardless of this setting.

clientMetadata

Object — Metadata about the verifier that wallets may display to users during the presentation flow. Corresponds to the client_metadata parameter defined in OID4VP and RFC 7591.

All fields within clientMetadata are optional. Fields that support internationalisation can have language-tagged variants using the format "field_name#language-tag" (e.g. "client_name#fr-FR"). Language tags follow BCP 47.

FieldTypeDescription
client_nameStringHuman-readable name of the verifier.
logo_uriStringURL pointing to the verifier's logo image.
tos_uriStringURL to a human-readable Terms of Service document.
policy_uriStringURL to a human-readable Privacy Policy document.
client_uriStringURL to the verifier's homepage.
vp_formats_supportedObjectCredential and proof formats the verifier accepts (per OID4VP §11.1). If not set, the service automatically injects a default declaring mso_mdoc support with ES256, -9, and -50 issuer auth algorithms.
jwksObjectJWK Set for wallet response encryption (per RFC 7517). For DC API flows with encrypted response (encrypted_response: true), this field is ignored — the service generates an ephemeral P-256 ECDH-ES key automatically.
encrypted_response_enc_values_supportedArrayJWE enc algorithms supported for encrypting the VP response. For DC API encrypted response flows, this is hardcoded to ["A128GCM"] by the service and any configured value is overridden.

urlPrefix

String — The base URL the service will use to construct the request_uri and response_uri endpoints returned to wallets. Wallets fetch the authorization request from {urlPrefix}/{sessionId}/request and post their VP response to {urlPrefix}/{sessionId}/response. Must be publicly reachable by the wallet.

urlPrefix is only used for OID4VP flows (cross-device and same-device). For DC API flows, this field must be absent — passing it with a DC API request will cause session creation to fail with a validation error.

Example: "http://localhost:7003/verification-session"

urlHost

String — The base URL used to construct the QR code link or deep link handed to the wallet. The authorization request URL is built by appending the authorization request parameters to this value.

  • Use "openid4vp://authorize" for OID4VP flows where the wallet is invoked via a deep link or QR code scan.
  • Use a full HTTPS URL for conformance testing with a browser-based authorization endpoint.

For DC API flows, urlHost is not used from config — it is derived from expectedOrigins (Annex D) or origin (Annex C) provided in the request body.

key (optional)

JWK Object — A JSON Web Key used to sign the authorization request JWT. The key must be provided in JWK format wrapped in a {"type":"jwk","jwk":{...}} object.

The key field does not control whether requests are signed. Signing is enabled per-request by setting signed_request: true in the verification session setup. When signed_request: true, a signing key is required — either configured here or supplied per-request. If neither is present, session creation will fail.

x5c (optional)

Array of Strings — An ordered X.509 certificate chain in DER-encoded, Base64-encoded format. The first certificate must correspond to the key. Required when using x509_san_dns: or x509_hash: as the clientId format, as wallets will use the certificate chain to verify the verifier's identity.

For signed Annex C (ISO 18013-7) requests, x5c is explicitly required — session creation will fail without it.

Full Example

verifier-service.conf
clientId: "verifier2"
# clientId: "x509_san_dns:verifier.example.com"
# clientId: "x509_hash:<base64url-cert-hash>"

clientMetadata: {
    client_name: "My Verifier"
    "client_name#fr-FR": "Mon Vérificateur"

    logo_uri: "https://example.com/logo.png"

    tos_uri: "https://example.com/terms"
    "tos_uri#fr-FR": "https://example.com/terms-fr"

    policy_uri: "https://example.com/privacy"
    "policy_uri#fr-FR": "https://example.com/privacy-fr"

    client_uri: "https://example.com"
}

# Used for OID4VP flows only. Not applicable to DC API flows.
urlPrefix: "http://localhost:7003/verification-session"
urlHost: "openid4vp://authorize"

# Required when signed_request: true is set in the verification session setup.
# key: {"type":"jwk","jwk":{"kty":"EC","crv":"P-256",...}}

# Required when using x509_san_dns or x509_hash clientId formats.
# x5c: ["MIIBVz..."]
Last updated on May 18, 2026
WebDev Mode