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

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 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.
`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.
`proof_types_supported`	Object	No	Wallet key-proof types. See co-dependency.
`credential_metadata`	Object	No	Per-credential display and claim descriptions. See 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.

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:<method> — e.g. did:key, did:jwk, did:web, did:ebsi

proof_types_supported is a map keyed by proof type (typically jwt):

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 <baseUrl>/openid4vci/<credentialConfigurationId>.
The issuer serves the corresponding VCT type metadata at /.well-known/vct/<credentialConfigurationId>.

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.

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)

"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)

"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)

"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

# 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"
        }
      ]
    }
  }
}

Issuer Profiles – Binds a credentialConfigurationId from this file to an issuer key and credential data (issuer2-profiles.conf)
Issuer Service – Core service configuration, including the baseUrl used to build the published metadata

Last updated on July 1, 2026

Issuer Service Issuer Profiles