Skip to content

NPA-5116 Add API Authentication Documentation #224

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
JackPlowman merged 5 commits into from
Jun 18, 2025
Merged

NPA-5116 Add API Authentication Documentation #224

Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
41b40bc
NPA-5116 Add Generic Authorisation Documentation
JackPlowman Jun 18, 2025
5de7180
NPA-5116 Docuemnt each endpoint authentication allowed methods
JackPlowman Jun 18, 2025
105fdcd
NPA-5116 Improve Wording
JackPlowman Jun 18, 2025
c40c598
NPA-5116 Improve Links and Titles
JackPlowman Jun 18, 2025
1e093b6
NPA-5116 Update Security and authorisation contents
JackPlowman Jun 18, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
82 changes: 73 additions & 9 deletions specification/validated-relationships-service-api.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -74,18 +74,42 @@ info:

## Security and authorisation

This API is [user-restricted](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation#user-restricted-apis), meaning an end user must be present, authenticated and authorised.
This API supports both [user-restricted](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation#user-restricted-apis) and [application-restricted](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation#application-restricted-apis) access types with the following access modes:

The end user must be:
* a patient who receives health and social care or makes use of NHS services
* strongly authenticated, using [NHS login](https://digital.nhs.uk/services/nhs-login)
| Access mode | Access type |
|-------------------------------|------------------------|
| Patient access | User-restricted |
| Healthcare worker access | User-restricted |
| Application-restricted access | Application-restricted |

To use this access mode, use one of the following security patterns:
For more information on access modes and how to use them, see the developer [security and authorisation guide](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation).

| Security pattern | Technical details | Advantages | Disadvantages |
|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| ----------------------------------------------------| ------------------------------------------------------------|---------------------------------------------------------|
|[NHS login - combined authentication and authorisation](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation/user-restricted-restful-apis-nhs-login-combined-authentication-and-authorisation) |OAuth 2.0 authorisation code with API key and secret |No need to integrate and onboard separately with NHS login. |No access to user information. |
|[NHS login - separate authentication and authorisation](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation/user-restricted-restful-apis-nhs-login-separate-authentication-and-authorisation) |OAuth 2.0 token exchange with signed JWT |Gives access to user information. |Need to integrate and onboard separately with NHS login. |
### User-restricted access

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`

#### Healthcare worker access mode
If the end user is a healthcare worker then you must use this access mode.

[Review all CIS2 healthcare worker access modes](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation#healthcare-worker-access-mode)

### Application-restricted access

This API is application-restricted, meaning we authenticate the calling application but not the end user.

[Review all application-restricted access modes](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation#application-restricted-apis)

## Headers
This API is case-insensitive when processing request headers, meaning it will accept headers regardless of the letter casing used. (e.g. X-Request-Id, x-request-id are treated the same). When sending headers back in the response, we preserve the exact casing as received in the original request.
Expand Down Expand Up @@ -162,6 +186,11 @@ paths:

For the most part demographics information doesn't need to be provided in the access request since it can be pulled from PDS.

## Access modes

This endpoint supports the following access modes:
- Patient access

## Sandbox test scenarios

| Scenario | Request | Response |
Expand Down Expand Up @@ -267,6 +296,12 @@ paths:
A valid reference code must be provided as a query parameter. This reference code is returned
when a QuestionnaireResponse is initially submitted via the POST endpoint.

## Access modes

This endpoint supports the following access modes:
- Patient access
- Healthcare worker access

## Sandbox test scenarios

| Scenario | Request | Response |
Expand Down Expand Up @@ -356,6 +391,12 @@ paths:

You can (optionally) include the `_include=RelatedPerson:patient` request parameter to include the patient's details in the response.

## Access modes

This endpoint supports the following access modes:
- Patient access
- Healthcare worker access

## Sandbox test scenarios

| Scenario | Request | Response |
Expand Down Expand Up @@ -475,6 +516,13 @@ paths:

You can (optionally) include the `_include=Consent:patient` request parameter to include the patient's details in the response.

## Access modes

This endpoint supports the following access modes:
- Patient access
- Healthcare worker access
- Application-restricted access

## Sandbox test scenarios

| Scenario | Request | Response |
Expand Down Expand Up @@ -618,6 +666,11 @@ paths:
## Overview
Use this endpoint to create a new proxy role between a patient and a related person (proxy).

## Access modes

This endpoint supports the following access modes:
- Healthcare worker access

## Sandbox test scenarios

The sandbox supports a limited number of scenarios, and does not attempt to validate requests. The returned result is dependant on the `performer.identifier.value`.
Expand Down Expand Up @@ -744,6 +797,11 @@ paths:

You can (optionally) include the `_include=Consent:patient` request parameter to include the patient's details in the response.

## Access modes

This endpoint supports the following access modes:
- Healthcare worker access

## Sandbox test scenarios

The sandbox supports a limited number of scenarios, and does not attempt to validate requests. The returned result is dependant on the `ID` for the consent resource.
Expand Down Expand Up @@ -857,6 +915,12 @@ paths:
* JSON Patch operations must be valid according to RFC 6902
* Status changes must use valid status codes from <http://hl7.org/fhir/consent-state-codes>

## Access modes

This endpoint supports the following access modes:
- Patient access
- Healthcare worker access

## Sandbox test scenarios
The sandbox supports a limited number of scenarios, and does not attempt to validate requests. The returned response is dependant on the `id` parameters.

Expand Down