GOV.UK One Login Technical Documentation

GOV.UK One Login Technical Documentation - One Login technical documentation

Cookies on GOV.UK Sign In

We’d like to use analytics cookies so we can understand how you use this website and make improvements.

Accept analytics cookies

Reject analytics cookies

View cookies

You’ve accepted analytics cookies. You can
change your cookie settings
at any time.

Hide this message

You’ve rejected analytics cookies. You can
change your cookie settings
at any time.

Hide this message

Skip to main content

Table of contents

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

Mar 6 2026

Updated
“Set your sector identifier”
to emphasise that sector identifiers must be a valid URL using the HTTPS scheme.

Feb 18 2026

Updates
guidance to add details that audience claim can be either token URI or issuer URI
.

Feb 17 2026

Updates guidance
“Share your public keys using a JWKS endpoint”
to clarify how to use a JWKS endpoint.

Feb 16 2026

Updates website header to clarify this website is the technical documentation for GOV.UK One Login.

Jan 19 2026

Added new diagram
“GOV.UK One Login OIDC Flow”
in UML format which describes the authorisation flow in more detail.

Nov 10 2026

Updates guidance
“Use the integration discovery endpoint”
to add information about caching.

Nov 5 2025

Updates guidance
“Replace the placeholder values in your example”
to explain the use of the
response_mode
parameter passed to the
/authorize
endpoint.

Oct 28 2025

Updates guidance
“Validate your ID token”
to explain the frequency of key rotations for the environments.

Oct 23 2025

Added guidance
“Setting a User-Agent header on HTTP requests”
the requirement to use an appropriate
User-Agent
header on service calls to GOV.UK One Login.

Sep 2 2025

Updates guidance
“Prove your user’s identity”
with guidance for helping your users after their in-person identity checks.

Jul 30 2025

Updates guidance
“Choose which scopes your service can request”
and
“Retrieve user information”
to add information about the
wallet-subject-id
scope.

Jun 12 2025

Updates section on testing to remove guidance on building mocks and move guidance on
“using the GOV.UK One Login simulator”
to section on
“testing your integration with GOV.UK One Login”
.

May 2 2025

Updates
guidance to add information about using Proof Key for Code Exchange (PKCE) parameters in the authorise request.
Updates guidance
to include information about using PKCE parameters in the token request.
Updates guidance
to include guidance about
PKCEEnforced
field when configuring your service
.

Apr 15 2025

Updates guidance
“Managing user sessions if your service session is less than 1 hour”
to add guidance on how to re-authenticate your users. Updates the
‘Make a request to the /authorize endpoint’ table
to add an entry for
login_required
error code.

Apr 2 2025

New guidance
“Test your service with the GOV.UK One Login simulator”
to add information about the new GOV.UK One Login simulator.

Mar 5 2025

Updates guidance
“Integrating third-party platforms”
to add guidance on integrating with GOV.UK One Login using Amazon Cognito.

Feb 17 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.

Jan 27 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
max_age
parameter.

Jan 21 2025

New guidance
“Quick start”
to help users see how a typical integration with GOV.UK One Login works.

Oct 23 2024

Updates guidance
“Understand the core identity signing key rotations”
to add information on the frequency of key rotations for the environments.

Oct 22 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.

Sep 25 2024

Updates guidance
“Register and manage your service”
to add guidance on how to register and manage a service.

Sep 17 2024

Updates guidance
“Integrating third-party platforms”
to add guidance on integrating with GOV.UK One Login using Salesforce.

Sep 6 2024

Updates guidance
“Use the production discovery endpoint”
to add the production discovery endpoint.

Aug 21 2024

Updates guidance
“Configure your service for production”
to add information about how to configure your service for production.

Aug 20 2024

Updates guidance
“Receive response for ‘Retrieve user information’”
to add a table explaining more about the response from the
/userinfo
endpoint.

Jul 29 2024

Updates guidance
“Error handling for ‘Make a request to the /authorize endpoint”
to update we now return HTTP 400 Bad Request errors for requests with incorrect parameters.

Jul 18 2024

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.

Jul 9 2024

Removes the
https://vocab.account.gov.uk/v1/socialSecurityRecord
claim

Jul 4 2024

New guidance
“Integrating third-party platforms”
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.

Jun 21 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.

Jun 18 2024

Includes example data to help with building mocksAccess example data.

May 22 2024

New guidance
Using the integration environment for end-to-end testing
to explain how to use the integration environment for end-to-end testing.

May 17 2024

New guidance Build mocks to work with GOV.UK One Login to explain how to build mocks as a part of testing your service.

May 2 2024

New guidance
Managing your users’ sessions
to explain how to manage your users’ sessions and how to build a logout mechanism for your users.

Apr 9 2024

Updates the
technical flow diagram
to document the use of the
/logout
endpoint.

Apr 3 2024

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.

Mar 25 2024

Removes references to the refresh token and
offline_access
to simplify integration and the technical flow.

Feb 14 2024

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.

Dec 22 2023

Updates guidance on making a request to the
/authorize
endpoint.

Dec 21 2023

New guidance
Secure your authorisation request parameters with JWT
using a JWT-secured OAuth 2.0 authorisation request (JAR) to improve the security of your integration and protect against tampering.

Oct 31 2023

New guidance
Before you integrate with GOV.UK One Login
.

This page was last reviewed on 20 April 2026.