---
title: "Verifier Service"
description: "Configure the Verifier2 service identity, URL settings, and signing key using verifier-service.conf."
stack: "Community Stack (open source) — version 0.21.0"
stack_version: "0.21.0"
stack_comparison: https://docs.walt.id/community-vs-enterprise.md
canonical_url: https://docs.walt.id/community-stack/verifier2/configurations/config-files/verifier-service
generated: 2026-07-20
---
# 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.

**Note:**

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](https://www.rfc-editor.org/rfc/rfc7591).

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](https://www.rfc-editor.org/rfc/bcp/bcp47.txt).

| Field | Type | Description |
|---|---|---|
| `client_name` | String | Human-readable name of the verifier. |
| `logo_uri` | String | URL pointing to the verifier's logo image. |
| `tos_uri` | String | URL to a human-readable Terms of Service document. |
| `policy_uri` | String | URL to a human-readable Privacy Policy document. |
| `client_uri` | String | URL to the verifier's homepage. |
| `vp_formats_supported` | Object | Credential 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. |
| `jwks` | Object | JWK 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_supported` | Array | JWE `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.

**Error:**

`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.

**Note:**

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

```editorconfig[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..."]
```