Publish your metadata
The metadata endpoint provides essential configuration information about a credential issuer’s implementation. To issue credentials, you must publish your metadata endpoint so that GOV.UK Wallet and verifiers can learn information about your credential issuer, such as:
- the endpoints used in your issuance flow
- the supported credential types
- how your credentials should be displayed
Technical details
Endpoint location
Your metadata must be publicly accessible at the standardised location on your credential issuer domain: /.well-known/openid-credential-issuer. The data published is non-sensitive metadata about your service.
Response format
The endpoint must return a 200 OK HTTP status code and valid JSON response that follows the OID4VCI specification.
Your metadata must include the following parameters:
| Parameter | Description |
|---|---|
credential_issuer |
The URL of the credential issuer. |
authorization_servers |
An array of URLs for the authorization servers your credential issuer relies on for authorization. This must be set to the GOV.UK One Login URL. |
credential_endpoint |
The URL of your credential issuer’s credential endpoint, where credentials can be obtained. |
credential_configurations_supported |
An object describing the credentials offered by your credential issuer. |
If your credential issuer implements the optional notification endpoint, then the metadata must include the notification_endpoint parameter.
You can define and use additional metadata parameters.
Credential information
The credential_configurations_supported object contains key-value pairs, where:
- each key is a unique identifier of a verifiable credential supported by the credential issuer
- each value is the configuration of that verifiable credential
Each credential object in credential_configurations_supported must include the following parameters:
formatcredential_definitioncryptographic_binding_methods_supportedcredential_signing_alg_values_supportedproof_types_supported
GOV.UK Wallet also requires your credential issuer’s metadata to support English and Welsh translation.
If you want to prompt users to refresh a credential after it expires, you can also include the optional credential_refresh_web_journey_url parameter. This is a custom parameter that is not part of the OID4VCI specification. You must set credential_refresh_web_journey_url to the URL where your users can go through the credential refresh web journey in their browser.
If you include a refresh URL you must also include the credential_validity_period_max_days parameter, which specifies the credential’s validity period in days once it’s issued. If the credential’s validUntil date or expiryDate ends before your specified validity period, then the credential will expire earlier. For example, if you set credential_validity_period_max_days to 90 days but the credential’s expiryDate will pass in 30 days’ time, then the credential will only be valid for 30 days.
Below is an example of the credential_refresh_web_journey_url and credential_validity_period_max_days parameters:
"credential_refresh_web_journey_url": "https://example-credential-issuer.gov.uk/fishing-refresh",
"credential_validity_period_max_days": 90
For more information, there is guidance on refreshing credentials.
Metadata example
Below is an example of a credential issuer metadata:
{
"credential_issuer": "https://example-credential-issuer.gov.uk",
"authorization_servers": ["https://token.account.gov.uk"],
"credential_endpoint": "https://example-credential-issuer.gov.uk/credential",
"notification_endpoint": "https://example-credential-issuer.gov.uk/notification",
"credential_configurations_supported": {
"FishingLicenceCredential": {
"format": "jwt_vc_json",
"credential_definition": {
"type": [
"VerifiableCredential",
"FishingLicenceCredential"
]},
"cryptographic_binding_methods_supported": [
"did"
],
"credential_signing_alg_values_supported": [
"ES256"
],
"proof_types_supported": {
"jwt": {
"proof_signing_alg_values_supported": [
"ES256"
]
}
},
"credential_refresh_web_journey_url": "https://example-credential-issuer.gov.uk/fishing-refresh",
"credential_validity_period_max_days": 90
}
}
}