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:
| Parameter | Description |
|---|---|
format |
Format of the credential. |
credential_definition |
Description of the credential type. |
cryptographic_binding_methods_supported |
Set of methods available for cryptographically binding the issued credential. |
credential_signing_alg_values_supported |
Set of algorithms that the credential issuer uses to sign the credential. |
proof_types_supported |
Key proof(s) supported by the credential issuer. |
credential_refresh_web_journey_url |
The URL where your users can go through the credential refresh web journey in their browser. |
credential_validity_period_max_days |
The credential’s validity period in days once it’s issued. |
GOV.UK Wallet also requires your credential issuer’s metadata to support English and Welsh translation.
Credential expiry
Your metadata endpoint response must include the following custom parameters:
credential_refresh_web_journey_urlcredential_validity_period_max_days
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. The credential_validity_period_max_days specifies the credential’s validity period in days once it’s issued.
If the credential’s validUntil date or expiryDate ends before your chosen validity period, 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, the credential will only be valid for 30 days.
More information about refreshing credentials is available.
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_refresh_web_journey_url": "https://example-credential-issuer.gov.uk/fishing-refresh",
"credential_validity_period_max_days": 90,
"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"
]
}
}
}
}
}