Publish your Decentralised Identifier (DID) document
As a credential issuer, you must use decentralised identifiers (DIDs) as they let GOV.UK Wallet verify the credentials it receives from credential issuers.
The DID document endpoint exposes your DID document, which contains the public cryptographic keys used to verify signatures on credentials issued by the credential issuer. This process checks the credentials’ authenticity and integrity.
Technical details
Endpoint location
Your DID document must be publicly accessible at the standardised location /.well-known/did.json on your domain.
Response format
The endpoint must return a 200 OK HTTP status code and a valid JSON response that follows the W3C Decentralized Identifiers (DIDs) v1.0 specification.
Your DID document must include the following parameters:
| Parameter | Description |
|---|---|
@context |
A set of URI references that define the meaning of the terms used in the DID document, allowing its properties to be correctly interpreted. |
id |
The decentralised identifier of the credential issuer in the format did:web:<CREDENTIAL_ISSUER_DOMAIN>. |
verificationMethod |
An array of verification methods containing your public keys. |
assertionMethod |
An array listing which verification methods you can use for making assertions - in the context of the credential issuer, this means issuing credentials. Each item must be the full identifier of a verification method, for example did:web:<CREDENTIAL_ISSUER_DOMAIN>#<KEY_ID>. |
Each object in the verificationMethod array must contain the following parameters:
| Parameter | Description |
|---|---|
id |
A unique identifier for the verification method in the format did:web:<CREDENTIAL_ISSUER_DOMAIN>#<KEY_ID> - this corresponds to the kid (key ID) parameter in the header of issued credentials. |
type |
The cryptographic suite used for verification - this must be JsonWebKey2020 as the JSON Web Signature 2020 specification is used |
controller |
The entity (you, as the credential issuer in this case) that has the authority to use the private key associated with the verification method - this must be in the format did:web:<CREDENTIAL_ISSUER_DOMAIN>. |
publicKeyJwk |
Your public key - this is represented as a JSON Web Key (JWK) and contains parameters specific to the elliptic curve algorithm used (P-256) |
Each object in the verificationMethod array represents a public key, which is the counterpart to the private key held securely by the credential issuer. These private keys are used to sign credentials. GOV.UK Wallet only accepts credentials signed using an elliptic curve key based on the P-256 curve.
Not all public keys listed in the verificationMethod are authorised for credential issuance. The assertionMethod array acts as an allow list, specifying which of those keys are trusted for credential issuance. Each item in assertionMethod directly references a public key in the verificationMethod array using its unique ID.
When GOV.UK Wallet receives a credential issued by the credential issuer, it uses the kid (key ID) in the credential’s header to find the matching public key in the verificationMethod array. It then checks if the same verification method ID is in the assertionMethod array. This confirms the key used to sign the credential was authorised for credential issuance by the DID controller (you, as the credential issuer).
DID document example
This is an example of a DID document containing an elliptic curve key based on the P-256 curve:
{
"@context": [
"https://www.w3.org/ns/did/v1",
"https://w3id.org/security/suites/jws-2020/v1"
],
"id": "did:web:example-credential-issuer.gov.uk",
"verificationMethod": [
{
"id": "did:web:example-credential-issuer.gov.uk#5dcbee863b5d7cc30c9ba1f7393dacc6c16610782e4b6a191f94a7e8b1e1510f",
"type": "JsonWebKey2020",
"controller": "did:web:example-credential-issuer.gov.uk",
"publicKeyJwk": {
"kty": "EC",
"kid": "5dcbee863b5d7cc30c9ba1f7393dacc6c16610782e4b6a191f94a7e8b1e1510f",
"crv": "P-256",
"x": "6jCKX_QRrmTeEJi-uiwcYqu8BgMgl70g2pdAst24MPE",
"y": "icPzjbSk6apD_SNvQt8NWOPlPeGG4KYU55GfnARryoY",
"alg": "ES256"
}
}
],
"assertionMethod": [
"did:web:example-credential-issuer.gov.uk#5dcbee863b5d7cc30c9ba1f7393dacc6c16610782e4b6a191f94a7e8b1e1510f"
]
}