GOV.UK One Login
GOV.UK One Login is the way for government services to:
- sign in their users
- prove their users’ identity
This technical documentation gives you information on how to:
- plan the functionality your service needs
- register your service with GOV.UK One Login
- integrate with GOV.UK One Login to authenticate users and prove their identity
- configure your service for production
You can read further documentation about how GOV.UK One Login works.
Contact us if you have any questions on our #govuk-one-login Slack channel.
Documentation updates
These are the most recent changes to this documentation.
| Publication date | Update |
|---|---|
| 7 Apr 2026 | Updates guidance “Authenticate your user” to improve the explanation of the state parameter. |
| 6 Mar 2026 | Updates “Set your sector identifier” to emphasise that sector identifiers must be a valid URL using the HTTPS scheme. |
| 18 Feb 2026 | Updates guidance “Make a token request” to add details that audience claim can be either token URI or issuer URI. |
| 17 Feb 2026 | Updates guidance “Share your public keys using a JWKS endpoint” to clarify how to use a JWKS endpoint. |
| 16 Feb 2026 | Updates website header to clarify this website is the technical documentation for GOV.UK One Login. |
| 19 Jan 2026 | Adds new diagram “GOV.UK One Login OIDC Authorization Code Flow” in UML format which describes the authorisation flow in more detail. |
| 10 Nov 2025 | Updates guidance “Use the integration discovery endpoint” to add information about caching. |
| 5 Nov 2025 | Updates guidance “Replace the placeholder values in your example” to explain the use of the response_mode parameter passed to the /authorize endpoint. |
| 28 Oct 2025 | Updates guidance “Validate your ID token” to explain the frequency of key rotations for the environments. |
| 23 Oct 2025 | Adds guidance “Setting a User-Agent header on HTTP requests” on the requirement to use an appropriate User-Agent header on service calls to GOV.UK One Login. |
| 2 Sep 2025 | Updates guidance “Prove your user’s identity” with information on helping your users after their in-person identity checks. |
| 30 Jul 2025 | Updates guidance “Choose which scopes your service can request” and “Retrieve user information” to add information about the wallet-subject-id scope. |
| 12 Jun 2025 | Updates section on testing to remove guidance on building mocks and move guidance on using the GOV.UK One Login simulator to “Test your integration with GOV.UK One Login” section. |
| 2 May 2025 | Updates guidance “Make a request to the /authorize endpoint” and “Make a token request” to add information about using Proof Key for Code Exchange (PKCE) parameters. Updates guidance “Configure your service for production” to include guidance about PKCEEnforced field. |
| 2 Apr 2025 | Adds new guidance “Test your service with the GOV.UK One Login simulator” to add information about the new GOV.UK One Login simulator. |
| 5 Mar 2025 | Updates guidance “Integrating third-party platforms with GOV.UK One Login” to add guidance on integrating with GOV.UK One Login using Amazon Cognito. |
| 17 Feb 2025 | Updates guidance “Using the integration environment for end-to-end testing” to remove reference to the integration environment basic authentication challenge which has been removed and is no longer required. |
| 27 Jan 2025 | Updates guidance “Authenticate your user” to add information about using the max_age parameter. Updates guidance “Generate an authorisation code” to add information about validating the max_age parameter. |
| 21 Jan 2025 | Adds new guidance “Quick start” to help users see how a typical integration with GOV.UK One Login works. |
| 23 Oct 2024 | Updates guidance “Understand the core identity signing key rotations” to add information on the frequency of key rotations for the environments. |
| 22 Oct 2024 | Updates and renames ‘Generate a key pair’ page to include new guidance “Share your public keys using a JWKS endpoint” to add other option when sharing your public key with GOV.UK One Login. |
| 25 Sep 2024 | Updates guidance “Register and manage your service” to add guidance on how to register and manage a service. |
| 17 Sep 2024 | Updates guidance “Integrating third-party platforms with GOV.UK One Login” to add guidance on integrating with GOV.UK One Login using Salesforce. |
| 6 Sep 2024 | Updates guidance “Use the production discovery endpoint” to add the production discovery endpoint. |
| 21 Aug 2024 | Updates guidance “Configure your service for production” to add information about how to configure your service for production. |
| 20 Aug 2024 | Updates guidance “Receive response for ‘Retrieve user information’” to add a table explaining more about the response from the /userinfo endpoint. |
| 29 Jul 2024 | Updates guidance “Error handling for ‘Make a request to the /authorize endpoint” to update how we now return HTTP 400 Bad Request errors for requests with incorrect parameters. |
| 18 Jul 2024 | Adds new guidance “Validate the core identity claim JWT using a public key”. Contains information about validating the core identity claim JWT using a public key, which GOV.UK One Login publishes in its Decentralized Identifier (DID) documents. |
| 9 Jul 2024 | Removes the https://vocab.account.gov.uk/v1/socialSecurityRecord claim. |
| 4 Jul 2024 | Adds new guidance “Integrating third-party platforms with GOV.UK One Login” which contains information about integrating with GOV.UK One Login using a third-party platform, and contains details about the client_secret_post token authentication method. |
| 21 Jun 2024 | Updates guidance “Error handling for ‘Make a request to the /authorize endpoint” to clarify the {"message": "Internal server error"}HTTP 502 Bad Gateway error. |
| 18 Jun 2024 | Includes example data to help with building mocks: “Access example data”. |
| 22 May 2024 | Adds new guidance “Using the integration environment for end-to-end testing” to explain how to use the integration environment for end-to-end testing. |
| 17 May 2024 | Adds new guidance ‘Build mocks to work with GOV.UK One Login’ to explain how to build mocks as a part of testing your service. |
| 2 May 2024 | Adds new guidance “Managing your users’ sessions” to explain how to manage your users’ sessions and how to build a logout mechanism for your users. |
| 9 Apr 2024 | Updates the technical flow diagram to document the use of the /logout endpoint. |
| 3 Apr 2024 | Adds new guidance “Understand your user’s return code claim” which gives information about any issues with the evidence your user provided to prove their identity. |
| 25 Mar 2024 | Removes references to the refresh token and offline_access to simplify integration and the technical flow. |
| 14 Feb 2024 | Adds new guidance “Choose your sector identifier” to explain the use of the sector identifier with a worked example that shows the effect of choosing different sector identifiers. |
| 22 Dec 2023 | Updates guidance on making a request to the /authorize endpoint. |
| 21 Dec 2023 | Adds new guidance “Secure your authorisation request parameters with JWT” on using a JWT-secured OAuth 2.0 authorisation request (JAR) to improve the security of your integration and protect against tampering. |
| 31 Oct 2023 | Adds new guidance “Before you integrate with GOV.UK One Login”. |
This page was last reviewed on 20 April 2026.