Skip to main content

DID document

The DID document endpoint lets GOV.UK Wallet verify the credentials it receives from credential issuers, who must use decentralised identifiers (DIDs).

This endpoint exposes the credential issuer’s 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

The DID document must be publicly accessible at the standardised location /.well-known/did.json on the credential issuer’s 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.

The DID document must include the following parameters:

  • @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 the credential issuer’s public keys

  • assertionMethod: An array listing which verification methods can be used for making assertions - in the context of the credential issuer, this means issuing credentials

Each object in the array must contain:

  • 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 (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: The credential issuer’s 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. Then, it checks if the same verification method ID is present in the assertionMethod array. This process confirms that the key used to sign the credential was authorised for credential issuance by the DID controller (the credential issuer).

DID document example

Below is an example of a DID document containing an elliptic curve key based on the P-256 curve in the verification method:

{
   "@context":[
      "https://www.w3.org/ns/did/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"
   ]
}
This page was last reviewed on 3 April 2025. It needs to be reviewed again on 3 October 2025 .