From 6aecda31b2057766b52a5ccaf4ae75125ff0941f Mon Sep 17 00:00:00 2001 From: Ellie Bound <175816742+ellie-bound1-NHSD@users.noreply.github.com> Date: Thu, 29 Jan 2026 11:54:20 +0000 Subject: [PATCH 1/2] NPA-6294: Content changes to spec --- specification/assets/overview.drawio.svg | 2 +- specification/im1-pfs-auth-api.yaml | 36 +++++++++--------------- 2 files changed, 15 insertions(+), 23 deletions(-) diff --git a/specification/assets/overview.drawio.svg b/specification/assets/overview.drawio.svg index d73aa2d9..f25ed95d 100644 --- a/specification/assets/overview.drawio.svg +++ b/specification/assets/overview.drawio.svg @@ -1,4 +1,4 @@ -
NHSE API Management Platform
[Software System]
Proxy
[Person]

PFS user
e.g. NHS app User
Patient Facing Service (PFS)
[Software System]

e.g. NHS app
GPIT
[Software System]

GPIT Supplier System
NHS England
[Organisation]
Validated Relationship Service
[Software System]

National Proxy Service API
NHS login
[Software System]

NHSE Identity provider
Log in
Authenticate
{ access token }
Initiate session
{ Proxy NHS number, Patient NHS number, Patient ODS Code }
Verify Martha's online account
and create a new IM1 session
Auth flow
Use IM1 endpoints as normal to access
services as the proxy on behalf of the patient
Get access token
{ composite proxy token }
Payload Specific to GPIT Supplier
IM1 PFS Auth
[Container: Apigee]

Proposed new proxy on NHSE API Management Platform
Auth Proxy
[Container: Apigee]

Access token issuance and verification
Homogenised
Payload
1
2
6
12
7
8
10
11
9
Manage services
for others
3
Existing process
Proposed  process
Legend
Get proxy roles

Get composite
proxy token for patient
5
Get proxy
roles
4a
4b
 \ No newline at end of file +
Authenticate Proxy on Patient's Behalf
API consumers
[Software System]

Patient Facing Service eg. NHS App
IM1 PFS Auth Proxy
(API Management)
[Container: Apigee]

API access & security services (amongst others)
Start Session
IM1 PFS Auth
[Container: Python Flask App]

Forwards Request onto GPIT system
Forwards API request to
GPIT
[Software System]

Initiates Session
IM1 PFS Auth
[Software System]
 \ No newline at end of file diff --git a/specification/im1-pfs-auth-api.yaml b/specification/im1-pfs-auth-api.yaml index d5dd42a6..e3150e7e 100644 --- a/specification/im1-pfs-auth-api.yaml +++ b/specification/im1-pfs-auth-api.yaml @@ -4,23 +4,26 @@ info: version: "0.1" description: | ## Overview - ![IM1 PFS Auth API High-level Diagram](https://raw.githubusercontent.com/NHSDigital/im1-pfs-auth/main/specification/assets/overview.drawio.svg) - An intermediary service to allow a proxy to act on behalf of their patient, regardless of GP practice they are registered to. Use this API to authenticate a user using an NHS login issued "proxy token" and initiate a session with the appropriate supplier system based on ODS code where an online account will be matched. A successful match would return newly established IM1 session details. + IM1 PFS Auth is an interface mechanism that provides authentication for PFS (Patient‑Facing Services). + This API lets a proxy act on behalf of a patient, regardless of the patient’s GP practice. + It authenticates the proxy using an NHS login proxy token and starts a session with the correct supplier system based on the patient’s ODS code. + If the patient’s online account can be matched, the API returns newly created IM1 session details. + + ![IM1 PFS Auth API High-level Diagram](https://raw.githubusercontent.com/NHSDigital/im1-pfs-auth/main/specification/assets/overview.drawio.svg) - You can: + You can use this API to: - - Authenticate a user and initiate a session with the approporiate supplier + - authenticate a proxy user and initiate a session with the appropriate supplier ## Who can use this API - This API can only be used where there is a legal basis to do so. Make sure you have this and a valid use case before - you go too far with your development by [contacting us](https://digital.nhs.uk/developer/help-and-support) + You can only use this API if you have a valid legal basis. + Before investing significant time in development, confirm that your use case is appropriate by [contacting us](https://digital.nhs.uk/developer/help-and-support). - You must do this before you can go live (see 'Onboarding' below). + You must do this before you can go live. ## API status and roadmap This API is [in development](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#statuses), meaning: - - we will be making breaking changes ## Technology This API is [RESTful](https://digital.nhs.uk/developer/guides-and-documentation/our-api-technologies#basic-rest). @@ -42,22 +45,16 @@ info: ### User-restricted access - User-restricted access meaning an end user must be present, authenticated and authorised. + This API has user-restricted access, meaning an end user must be present, authenticated and authorised. #### Patient access mode If the end user is a patient then you must use this access mode. [Review all patient access modes](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation#patient-access-mode) - Validated Relationships Service API checks the patient is P9 verified and has a high [vector of trust](https://nhsconnect.github.io/nhslogin/vectors-of-trust/) (VOT). - - Allowed vectors of trust are: - - `P9.Cp.Cd` - - `P9.Cp.Ck` - - `P9.Cm` ## Headers - This API is case-insensitive when processing request headers, meaning it will accept headers regardless of the letter casing used. (e.g. NHSE-Request-Id, nhse-request-id are treated the same). When sending headers back in the response, we preserve the exact casing as received in the original request. + This API is case-insensitive when processing request headers, meaning it will accept headers regardless of the letter casing used. For example, NHSE-Request-Id, nhse-request-id are treated the same. ## Errors We use standard HTTP status codes to show whether an API request succeeded or not. They are usually in the range: @@ -66,7 +63,7 @@ info: * 400 to 499 if it failed because of a client error by your application * 500 to 599 if it failed because of an error on our server - Errors specific to each API are shown in the Endpoints section, under Response. See our [reference guide](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#http-status-codes) for more on errors. + Each endpoint lists its own specific errors in the Responses section. See our [reference guide](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#http-status-codes) for more on errors. ## Open source You might find the following [open source](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#open-source) resources useful: @@ -92,11 +89,6 @@ info: Import the postman collection to run requests against sandbox. - ## Onboarding - You must get your software onboarded before it can go live. - - For more details, contact us at [england.vrs-team@nhs.net](mailto:england.vrs-team@nhs.net). - ## Contact us For help and support connecting to our APIs and to join our developer community, see [Help and support building healthcare software](https://digital.nhs.uk/developer/help-and-support). From eb67d7f385a743b285d233cedb82b93421eee844 Mon Sep 17 00:00:00 2001 From: Ellie Bound <175816742+ellie-bound1-NHSD@users.noreply.github.com> Date: Thu, 29 Jan 2026 15:29:55 +0000 Subject: [PATCH 2/2] NPA-6294: Review comments --- specification/im1-pfs-auth-api.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/im1-pfs-auth-api.yaml b/specification/im1-pfs-auth-api.yaml index e3150e7e..e82862bd 100644 --- a/specification/im1-pfs-auth-api.yaml +++ b/specification/im1-pfs-auth-api.yaml @@ -23,7 +23,7 @@ info: You must do this before you can go live. ## API status and roadmap - This API is [in development](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#statuses), meaning: + This API is [in development](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#statuses). ## Technology This API is [RESTful](https://digital.nhs.uk/developer/guides-and-documentation/our-api-technologies#basic-rest).