Use in-app credential refresh

In-app refresh lets your users refresh their credentials in the GOV.UK One Login app without returning to your service’s web journey. To do this, GOV.UK Wallet requests a refresh token from GOV.UK One Login when a credential is first issued. This refresh token lets your users refresh the credential up to 15 months after it was issued.

We recommend using in-app refresh as your main refresh method, as it is faster and simpler for your users.

You should use manual credential refreshing as a backup in case in-app refresh fails.

You must ask the GOV.UK Wallet onboarding team to enable in-app refresh for you when you onboard. You must also make changes to your credential for in-app refresh to work. If you previously issued credentials before in-app refresh was available, you must make additional changes.

Update credential expectedUpdate date

You must set an expectedUpdate date for your credential. This is the date on which GOV.UK Wallet will enable in-app refresh for this credential. In most cases, you should set expectedUpdate to a number of days before the credential’s validUntil date. This lets GOV.UK Wallet refresh the credential before the validUntil date passes.

If your user will reach a birthday where their entitlements change (18, 21 or 25) before the issued credential passes its validUntil date, you should set the credential’s expectedUpdate to the user’s upcoming birthday. On the expectedUpdate date, GOV.UK Wallet will attempt to refresh the 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.

Validate new access token

When your user refreshes their credential in the GOV.UK One Login app, GOV.UK Wallet will get a new access token from GOV.UK One Login. This token is the same as the access token you got the first time the credential was issued, except that it does not contain credential_identifiers. You must validate the new access token.

If you issued credentials before in-app refresh was available

If you previously issued credentials before in-app refresh was available, you must add credential_configuration_ids to the pre-authorised code JSON web token (JWT) payload in your credential offer.

The value you set for credential_configuration_ids must be the same as the name given in the metadata.

When you have added credential_configuration_ids to your pre-authorised code JWT payload, GOV.UK Wallet will call your credential endpoint with a new access token. You must validate the access token and make sure that its credential_configuration_ids value matches the value in your pre-authorised code JWT payload.

Understand GOV.UK Wallet’s automatic in-app refresh flow

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

  sequenceDiagram

autonumber
actor User as User
participant CRI as Credential Issuer
participant App as App
participant OneLogin as GOV.UK One Login

note over CRI,App: On credential expiry
    User->>App: Opens GOV.UK One Login App 
and opens the expired credential
    activate App
        App->>App: Credential expired,
shows refresh button
        User->>App: Presses credential refresh button
        App->>OneLogin: Exchanges refresh token 
for new access and refresh token
        activate OneLogin
        OneLogin->>OneLogin: Verifies refresh token request  
            OneLogin->>OneLogin: Generates new access and refresh token
            OneLogin-->>App: Returns new access and refresh token
        deactivate OneLogin
        App->>App: Generates proof of possession token
        App->>CRI: Fetches credential:
 POST /credential
    deactivate App
  

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

2. GOV.UK Wallet checks the credential and finds it has expired, been revoked by the issuer or passed its expectedUpdate date. The app shows the user a refresh button.

3. The user presses the credential refresh button in the app.

4. GOV.UK Wallet calls GOV.UK One Login to exchange the current refresh token for a new access token and refresh token.

5. GOV.UK One Login verifies the refresh token request.

6. GOV.UK One Login generates a new access token and refresh token.

7. GOV.UK One Login issues the new access token and refresh token to GOV.UK Wallet.

8. GOV.UK Wallet generates a proof of possession token for the credential request.

9. GOV.UK Wallet sends a POST request to your /credential endpoint to request the credential. This request includes the access token issued by GOV.UK One Login (as a bearer token in the authorization header) and the proof of possession token generated by GOV.UK Wallet.

Once GOV.UK One Login issues the new access token and refresh token to GOV.UK Wallet, your service can continue the credential issuance process.

This page was last reviewed on 20 February 2026. It needs to be reviewed again on 20 August 2026 .