Refresh credentials

Digital credentials in GOV.UK Wallet have a technical expiry date, which is when the digital version of a user’s credential is no longer valid and must be updated. You can set this technical expiry date using the validUntil claim in the credential. There is more guidance on credential expiration.

When a credential passes its validUntil date, it will fail programmatic verification and must be rejected by anyone who verifies it. The user will see their expired credential marked as ‘Invalid’ and greyed out in the app.

GOV.UK Wallet lets your users get a new credential without going through the longer credential issuance journey they used the first time it was issued. This is the manual credential refresh journey.

Update credential issuer metadata

To let your users manually refresh a credential, you must add the credential_refresh_web_journey_url parameter to your credential issuer metadata. This is a custom parameter that is not part of the OID4VCI specification.

credential_refresh_web_journey_url lets you specify a URL that jumps the user close to the end of the credential issuance journey. If this parameter is present in your metadata, your users will get a prompt to refresh when their credential passes its validUntil date.

When your user taps the ‘Refresh’ button in the app, the app will take the user to your specified URL to start their credential refresh web journey in their browser. At the end of this journey you must provide a new credential offer that GOV.UK Wallet can use to request a new credential.

You must also include the credential_validity_period_max_days parameter to set a maximum validity period after which the credential must be refreshed. When you include this parameter, GOV.UK Wallet will display the value on the refresh page so that users know how often they need to refresh their document.

You must get the information about the user’s existing credential from their user record. GOV.UK Wallet does not share any details about the user when they start your manual refresh journey.

If GOV.UK Wallet adds the new credential successfully, the user will only see the new credential in their documents. GOV.UK Wallet will remove the old credential.

Understand GOV.UK Wallet’s manual credential refresh flow

This diagram shows the exchange between a government service (the ‘credential issuer’) and GOV.UK Wallet when the user refreshes a credential. This diagram, and the descriptions below it, are an explanation of each step in the process.

  sequenceDiagram

  autonumber
  actor user
  participant ecri as Credential Issuer
  participant app as App

  note over ecri,app: On or near 
 credential expiry
  user->>app: Opens GOV.UK One Login App 
 and goes to the credential
  activate app
    app->>ecri: Gets credential issuer metadata 
`/.well-known/openid-credential-issuer`
    activate ecri
    ecri-->>app: Returns credential issuer metadata
    deactivate ecri
    app->>app: Finds `credential_refresh_web_journey_url` in metadata
    app->>app: Validates `credential_refresh_web_journey_url`
  deactivate app
  user->>app: Clicks 'Refresh' button
  app->>user: Opens `credential_refresh_web_journey_url` in user's browser
  

1. Your user opens the app and finds the credential they need to refresh.

2. GOV.UK Wallet sends a GET request to your /.well-known/openid-credential-issuer endpoint to fetch your credential issuer metadata.

3. Your service returns its credential issuer metadata.

4. The app finds the credential_refresh_web_journey_url value in the credential issuer metadata.

5. The app validates the credential_refresh_web_journey_url.

6. The user selects the ‘Refresh’ button in the app.

7. The app opens the issuer’s credential_refresh_web_journey_url in a browser on the user’s mobile device.

When the user’s browser has loaded your credential_refresh_web_journey_url, your service should:

1. Authenticate the user with GOV.UK One Login.
2. Determine if the user’s credential can be reissued.
3. Reissue the user’s credential through the credential issuance process.

This page was last reviewed on 16 December 2025. It needs to be reviewed again on 16 June 2026 .