Skip to main content

Manage keys

This page is specific to JWT credentials. When you issue mdoc credentials, you should check the ISO/IEC 18013-5 specification for information about credential rotation.

We are updating this documentation to provide more guidance about mdoc implementations. We will publish a documentation update when this guidance is available.

GOV.UK Wallet needs to verify the validity of the credentials your service issues.

When issuing credentials in JWT-VC format and signing with your private keys, your credentials need to be verified by the public keys you made available in the did:web document.

For your credential issuer service, you should include specific key management features:

  • Your service needs a key rotation process that periodically generates a new asymmetric key pair for signing new verifiable credentials, but that retains trust in previous public keys so that existing credentials remain verifiable. You can do this by making sure the public key of a retired private key is retained and published to the publicly accessible did:web document. To make sure your credentials can be verified if a private key expires, you must keep your public key in the did:web document until the credentials signed with it have expired. This is so that the signature on the credentials can be verified.
  • Your service also needs key revocation. This must include a notice from the credential issuer to explain that a specific key should be removed from operational use before it expires. This will generally happen when the key is lost or compromised. If a key is compromised, it can be used by an attacker to decrypt or forge messages, impersonate an identity, or access sensitive information.

This table describes the possible states of a key pair used for signing credentials:

Key State Description
Created A key pair is generated with an activation date in the future. It is not yet used for signing.
Active A key becomes active on the activation date, and enabled for signing and verifying the VC. There must not be multiple keys active at the same time.
Inactive A key becomes inactive past its expiration date or time. The public key will still be valid for verifying the VC.
Revoked A key is destroyed and removed from the issuer’s server, and is not valid for signing or verifying the signatures.
This page was last reviewed on 27 May 2026. It needs to be reviewed again on 27 November 2026 by the page owner #di-mobile-wallet-tech-docs .