--- title: "Credential Issuer Metadata" description: "Reference for the credential-issuer-metadata.conf configuration file." 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/issuer2/configurations/config-files/credential-issuer-metadata generated: 2026-07-20 --- # Credential Issuer Metadata Configuration The `credential-issuer-metadata.conf` file defines the OpenID4VCI credential issuer metadata: how the issuer presents itself, and which credential types it supports. Its contents are published at the `/.well-known/openid-credential-issuer/openid4vci` endpoint. The file has exactly **two top-level keys**: `issuerDisplay` and `credentialConfigurations`. Each is parsed into strongly-typed OpenID4VCI metadata objects at startup, so the structure below is validated — an invalid entry stops the service from loading. ## File Location ``` waltid-services/waltid-issuer-api2/config/credential-issuer-metadata.conf ``` ## Configuration Options | Property | Type | Required | Description | |----------|------|----------|-------------| | `issuerDisplay` | Array | No | How the issuer (name/logo) appears in wallets. | | `credentialConfigurations` | Object (map) | No | Supported credential types, keyed by credential configuration ID. | ## issuerDisplay A list of display entries for the **issuer itself**, typically one per locale. Purely presentational. | Field | Type | Required | Description | |-------|------|----------|-------------| | `name` | String | No | Issuer display name. | | `locale` | String | No | BCP-47 locale, e.g. `"en-US"`. | | `logo` | Object | No | Issuer logo. | | `logo.uri` | String | Yes (within `logo`) | Logo URL. Must be non-blank. | | `logo.alt_text` | String | No | Alternative text for the logo. | ```hocon issuerDisplay = [ { name = "Example Issuer" locale = "en-US" logo = { uri = "https://example.com/logo.png" alt_text = "Example Issuer Logo" } } ] ``` ## credentialConfigurations A map of the credential types this issuer supports. **The map key is the credential configuration ID** (e.g. `"UniversityDegree_jwt_vc_json"`). This ID is the contract point with the rest of the system: - Profiles in [`issuer2-profiles.conf`](https://docs.walt.id/community-stack/issuer2/configurations/config-files/issuer-profiles.md) reference it via `credentialConfigurationId`. - It is matched against OAuth scopes during issuance. ### Fields | Field | Type | Required | Description | |-------|------|----------|-------------| | `format` | String (enum) | **Yes** | Credential format. One of `jwt_vc_json`, `dc+sd-jwt`, `mso_mdoc`. | | `scope` | String | No | OAuth scope used to request this credential. Conventionally equal to the configuration ID. Must be non-blank if present. | | `credential_definition` | Object | No | For W3C VC formats: `{ "@context": [...], type: [...] }`. | | `doctype` | String | No | Document type for `mso_mdoc`, e.g. `org.iso.18013.5.1.mDL`. | | `vct` | String | No | Verifiable Credential Type for `dc+sd-jwt`. See [VCT handling](#vct-handling). | | `credential_signing_alg_values_supported` | Array | No | Format-specific (see below). Must be non-empty if present. | | `cryptographic_binding_methods_supported` | Array | No | Key binding methods. See [co-dependency](#binding-methods-and-proof-types). | | `proof_types_supported` | Object | No | Wallet key-proof types. See [co-dependency](#binding-methods-and-proof-types). | | `credential_metadata` | Object | No | Per-credential display and claim descriptions. See [credential_metadata](#credential_metadata). | | *(any other key)* | — | No | Passed through verbatim into the published metadata as a custom parameter. Must not reuse a standard field name above. | **Error:** Only `format` is strictly required by the schema. However, a credential type that wallets can actually request normally also needs `scope`, `cryptographic_binding_methods_supported`, `proof_types_supported` and `credential_signing_alg_values_supported`. ### Binding methods and proof types `cryptographic_binding_methods_supported` and `proof_types_supported` are **co-dependent**: if you set one, you must set the other. Setting only one stops the service from loading. **`cryptographic_binding_methods_supported`** accepts: - `jwk` - `cose_key` - `did:` — e.g. `did:key`, `did:jwk`, `did:web`, `did:ebsi` **`proof_types_supported`** is a map keyed by proof type (typically `jwt`): ```hocon proof_types_supported = { jwt = { proof_signing_alg_values_supported = ["ES256"] # required, non-empty } } ``` ### Signing algorithms `credential_signing_alg_values_supported` is validated against the `format`: | Format | Expected values | Example | |--------|-----------------|---------| | `jwt_vc_json`, `dc+sd-jwt` | JOSE algorithm names (strings) | `["ES256"]` | | `mso_mdoc` | COSE algorithm identifiers (integers), e.g. `-7` = ES256 | `[-7, -9]` | ### VCT handling For `dc+sd-jwt` credentials, set `vct` to the special value `"vctBaseUrl"` to publish a self-hosted VCT: - It is replaced at runtime with `/openid4vci/`. - The issuer serves the corresponding VCT type metadata at `/.well-known/vct/`. Any other string is published unchanged, so you can also point to an externally hosted VCT, e.g. `vct = "https://example.com/credentials/identity"`. ### credential_metadata Per-credential display and claim metadata lives **under `credential_metadata`** — not at the top level of the credential configuration. **Error:** A `display` (or `claims`) key placed directly on the credential configuration is **not** interpreted as OpenID4VCI display metadata. It is treated as a custom parameter and republished without validation. Put display and claims under `credential_metadata`. **`credential_metadata.display`** — optional list of display entries (one per locale; locales must be unique): | Property | Type | Required | Description | |----------|------|----------|-------------| | `name` | String | Yes | Credential display name (non-blank). | | `locale` | String | No | Locale code, e.g. `"en-US"`. | | `logo` | Object | No | `{ uri, alt_text }` — `uri` required and must include a scheme. | | `description` | String | No | Description of the credential. | | `background_color` | String | No | Hex color. | | `background_image` | Object | No | `{ uri }` — must include a scheme. | | `text_color` | String | No | Hex color. | **`credential_metadata.claims`** — optional list of claim descriptions: | Property | Type | Required | Description | |----------|------|----------|-------------| | `path` | Array<String> | Yes | Claim path (non-empty, no blank segments). | | `mandatory` | Boolean | No | Whether the claim is mandatory. | | `display` | Array | No | `{ name, locale }` entries; locales must be unique. | ## Credential Configuration Examples ### SD-JWT VC (dc+sd-jwt) ```hocon "identity_credential" = { format = "dc+sd-jwt" scope = "identity_credential" vct = "vctBaseUrl" cryptographic_binding_methods_supported = ["jwk", "did:key", "did:web"] credential_signing_alg_values_supported = ["ES256"] proof_types_supported = { jwt = { proof_signing_alg_values_supported = ["ES256"] } } credential_metadata = { display = [ { name = "Identity Credential" locale = "en-US" background_color = "#12107c" text_color = "#FFFFFF" } ] } } ``` ### W3C JWT VC (jwt_vc_json) ```hocon "UniversityDegree_jwt_vc_json" = { format = "jwt_vc_json" scope = "UniversityDegree_jwt_vc_json" cryptographic_binding_methods_supported = ["jwk", "did:key", "did:web", "did:jwk"] credential_signing_alg_values_supported = ["ES256"] proof_types_supported = { jwt = { proof_signing_alg_values_supported = ["ES256"] } } credential_definition = { type = ["VerifiableCredential", "UniversityDegree"] } credential_metadata = { display = [ { name = "University Degree" locale = "en-US" logo = { uri = "https://example.edu/logo.png" alt_text = "University Logo" } background_color = "#1e3a8a" text_color = "#FFFFFF" } ] } } ``` ### mDoc (mso_mdoc) ```hocon "org.iso.18013.5.1.mDL" = { format = "mso_mdoc" scope = "org.iso.18013.5.1.mDL" doctype = "org.iso.18013.5.1.mDL" cryptographic_binding_methods_supported = ["cose_key"] credential_signing_alg_values_supported = [-7, -9] # COSE identifiers, e.g. -7 = ES256 proof_types_supported = { jwt = { proof_signing_alg_values_supported = ["ES256"] } } credential_metadata = { display = [ { name = "Mobile Driver's License" locale = "en-US" logo = { uri = "https://example.gov/dmv-logo.png" alt_text = "DMV Logo" } } ] } } ``` ## Example Configuration ```hocon # credential-issuer-metadata.conf issuerDisplay = [ { name = "Example University" locale = "en-US" logo = { uri = "https://example.edu/logo.png" alt_text = "Example University Logo" } } ] credentialConfigurations = { "identity_credential" = { format = "dc+sd-jwt" scope = "identity_credential" vct = "vctBaseUrl" cryptographic_binding_methods_supported = ["jwk", "did:key", "did:web"] credential_signing_alg_values_supported = ["ES256"] proof_types_supported = { jwt = { proof_signing_alg_values_supported = ["ES256"] } } credential_metadata = { display = [ { name = "Identity Credential" locale = "en-US" background_color = "#12107c" text_color = "#FFFFFF" } ] } } "UniversityDegree_jwt_vc_json" = { format = "jwt_vc_json" scope = "UniversityDegree_jwt_vc_json" cryptographic_binding_methods_supported = ["jwk", "did:key", "did:web"] credential_signing_alg_values_supported = ["ES256"] proof_types_supported = { jwt = { proof_signing_alg_values_supported = ["ES256"] } } credential_definition = { type = ["VerifiableCredential", "UniversityDegree"] } credential_metadata = { display = [ { name = "University Degree" locale = "en-US" background_color = "#1e3a8a" text_color = "#FFFFFF" } ] } } } ``` ## Related Configuration - [Issuer Profiles](https://docs.walt.id/community-stack/issuer2/configurations/config-files/issuer-profiles.md) – Binds a `credentialConfigurationId` from this file to an issuer key and credential data (`issuer2-profiles.conf`) - [Issuer Service](https://docs.walt.id/community-stack/issuer2/configurations/config-files/issuer-service.md) – Core service configuration, including the `baseUrl` used to build the published metadata