Issuing credentials to GOV.UK Wallet

GOV.UK Wallet will support multiple credential formats to represent government documents. These documents can be:

• mdoc based credentials for the digital driving licence
• other Verifiable Credentials (VCs), including W3C Verifiable Credential Data Model 2.0 and later other formats allowing selective disclosure of attributes

GOV.UK Wallet follows the OpenID Connect for Verifiable Credential Issuance (OIDC4VCI) open standard for its issuance flow.

Your team or department can start issuing credentials to GOV.UK Wallet by following this documentation.

Understand GOV.UK Wallet’s credential exchange flow

This diagram shows the exchange of a credential between a government service and GOV.UK Wallet. Below the diagram is 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
    activate User
    User->>CRI: Accesses your service
    activate CRI
    CRI->>OneLogin: Authenticates user
    activate OneLogin
    OneLogin-->>CRI: Fetches user's walletSubjectID:
GET /userinfo
    deactivate OneLogin
    CRI->>CRI: Generates credential offer
    CRI-->>User: Renders credential offer
 as QR code or deep-link
    deactivate CRI
    User->>App: Opens app
    activate App
    App-->OneLogin: Authenticates user
    activate OneLogin
    OneLogin-->>App: User is authenticated
    deactivate OneLogin
    User->>App: Redeems credential offer
    App->>CRI: Fetches CRI's metadata:
 GET /.well-known/openid-credential-issuer
    activate CRI
    CRI-->>App: Returns metadata
    deactivate CRI
    App->>OneLogin: Exchanges pre-authorized code
 for access token
    activate OneLogin
    OneLogin->>CRI: Fetches CRI's public keys:
 GET /.well-known/jwks.json
    activate CRI
    CRI-->>OneLogin: Returns public keys as JWKS
    deactivate CRI
    OneLogin->>OneLogin: Verifies pre-authorized code
 content and signature
    OneLogin-->>App: Issues access token
    deactivate OneLogin
    App->>App: Generates proof of possession
    App->>CRI: Fetches credential:
 POST /credential
    activate CRI
        CRI->>OneLogin: Fetches GOV.UK One Login's public keys:
 GET /.well-known/jwks.json
        activate OneLogin
        OneLogin-->>CRI: Returns JWKS
        deactivate OneLogin
    CRI->>CRI: Verifies access token and
 proof of possession content and signature
    CRI->>CRI: Compares walletSubjectId values
    CRI->>CRI: Generates credential
    CRI->>App: Returns credential
    deactivate CRI
    App->>CRI: Fetches CRI's public key:
 GET /.well-known/did.json
    activate CRI
    CRI-->>App: Returns public key as DID document
    deactivate CRI
    App->>App: Verifies credential
 content and signature
    App->>App: Stores credential
    App->>CRI: Notifies of success or failure:
POST /notification
    activate CRI
    CRI->>CRI: Records notification
    CRI-->>App: Returns empty response
    deactivate CRI
    deactivate App
    deactivate User
    

User authenticates with GOV.UK One Login to use your service

1. Your user accesses your service.
2. Your service authenticates the user with GOV.UK One Login.
3. Your service fetches the user’s walletSubjectId from the GOV.UK One Login /userinfo API.

There is detailed guidance on how GOV.UK One Login works in the GOV.UK One Login technical documentation.

Your service issues a credential offer

4. Your service generates a credential offer. Included in this offer is a pre-authorised code signed by your service.
5. Your service renders the credential offer to the user as a QR code or deep-link.
6. The user opens the app.
7. The app prompts the user to authenticate with GOV.UK One Login.
8. The user who authenticated with your service in a web browser is authenticated with GOV.UK One Login in the app.
9. The user scans the QR code or opens the deep link. This action passes the credential offer to GOV.UK Wallet.

Your service publishes metadata about the credentials it publishes

10. GOV.UK Wallet sends a GET request to your /.well-known/openid-credential-issuer endpoint to fetch your metadata.
11. Your service returns its metadata.
12. GOV.UK Wallet calls GOV.UK One Login to exchange the pre-authorised code in the credential offer for an access token.
13. GOV.UK One Login sends a GET request to your /.well-known/jwks.json endpoint to fetch your public keys, which verify the signature on the pre-authorised code issued by your service.
14. Your service returns its public keys as a JSON Web Key Set (JWKS).
15. GOV.UK One Login verifies the pre-authorised code content and its signature.
16. GOV.UK One Login issues an access token that you can trust when GOV.UK Wallet calls your service to redeem it.
17. GOV.UK Wallet generates a proof of possession for the key material.
18. 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 generated by GOV.UK Wallet.

Your service issues a credential

19. Your service sends a GET request to the GOV.UK One Login /.well-known/jwks.json to fetch its public keys, which verify the signature on the access token issued by GOV.UK One Login.
20. GOV.UK One Login returns its public keys as a JSON Web Key Set (JWKS).
21. Your service verifies the content and signature of the access token and the proof of possession.
22. Your service compares the walletSubjectId in the access token’s sub claim with the walletSubjectId retrieved in step 3. If they are the same, this provides assurance that you are issuing the credential to a digital wallet that is logged in as the rightful holder.
23. Your service builds and signs the credential, and binds it to the did:key provided in the proof of possession to make sure the credential can only be used by the device it is issued to.
24. Your service returns the device-bound credential to GOV.UK Wallet.
25. GOV.UK Wallet sends a GET request to your /.well-known/did.json endpoint to fetch your DID document. The DID document contains your public key which is required to verify the signature on the credential issued by your service.
26. Your service returns its DID document.
27. GOV.UK Wallet verifies the content and signature of the credential.
28. GOV.UK Wallet stores the credential.

GOV.UK Wallet notifies your service

The following steps are optional. If you do not offer a /notification endpoint then GOV.UK Wallet will not send a notification.

29. GOV.UK Wallet sends a POST request to your /notification endpoint to notify your service. This notification will confirm whether GOV.UK Wallet successfully stored the credential, or failed to store it.
30. Your service records the notification.
31. Your service returns an empty response to GOV.UK Wallet.

This page was last reviewed on 14 May 2025. It needs to be reviewed again on 14 November 2025 .