Refresh credentials
GOV.UK Wallet lets your users get a new digital credential without going through the longer credential issuance journey they used the first time it was issued. This is the credential refresh journey.
How users can refresh credentials
Your users can refresh their credentials:
- in app, which lets your user refresh their credential without leaving the GOV.UK One Login app
- manually, which takes your user back to your service to refresh their credential
You should use in-app refresh as your main refresh method, as it is faster and simpler for your users.
You must use manual credential refresh:
- as a backup method if in-app refresh fails
- if your user’s refresh token has expired
- if you need to increase your user’s identity confidence to medium. There is guidance on choosing the level of identity confidence in the GOV.UK One Login technical documentation
If you do not provide a link to a shortened manual credential refresh journey in these scenarios, GOV.UK Wallet will redirect your user to the start of your service. In that case, your user will need to go through the full credential issuance journey to refresh their credentials.
When to ask the user to refresh credentials
When the credential passes its technical expiry date
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 must set this technical expiry date using the validUntil claim in the credential. There is more guidance on credential expiry.
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.
When the user’s details have changed
You can revoke a user’s credential, for example because they have changed their details. When you revoke a user’s credential, it will appear marked as ‘Invalid’ and greyed out in the app. It can take up to 8 hours for a credential to be marked as ‘Invalid’. There is guidance on revoking credentials.
When the user reaches a birthday where their entitlements change
When you issue a credential, you should check if the user will reach a birthday where their entitlements change (18, 21 or 25) before that credential passes its validUntil date. If they will, you should set the credential’s expectedUpdate to the user’s upcoming birthday. On the expectedUpdate date, GOV.UK Wallet will enable in-app refreshing for this credential. The previous credential will be valid until the validUntil date, but any age over {nn} checks will fail until the user successfully refreshes their credential.
Guidance on credentials issued before in-app refreshing
Your user may hold credentials that were issued before GOV.UK Wallet’s in-app refresh was deployed. In this case, you must first ask them to refresh this credential manually before they can use in-app refreshing.