Skip to content

Commit fe78aa2

Browse files
JackPlowmanJackPlowman
authored
Merge pull request #224 from NHSDigital/docs/NPA-5116_Auth_Docs
NPA-5116 Add API Authentication Documentation
2 parents e1aae11 + 1e093b6 commit fe78aa2

File tree

1 file changed

+73
-9
lines changed

1 file changed

+73
-9
lines changed

‎specification/validated-relationships-service-api.yaml‎

Lines changed: 73 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -74,18 +74,42 @@ info:
7474
7575
## Security and authorisation
7676
77-
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.
77+
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:
7878
79-
The end user must be:
80-
* a patient who receives health and social care or makes use of NHS services
81-
* strongly authenticated, using [NHS login](https://digital.nhs.uk/services/nhs-login)
79+
| Access mode | Access type |
80+
|-------------------------------|------------------------|
81+
| Patient access | User-restricted |
82+
| Healthcare worker access | User-restricted |
83+
| Application-restricted access | Application-restricted |
8284
83-
To use this access mode, use one of the following security patterns:
85+
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).
8486
85-
| Security pattern | Technical details | Advantages | Disadvantages |
86-
|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| ----------------------------------------------------| ------------------------------------------------------------|---------------------------------------------------------|
87-
|[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. |
88-
|[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. |
87+
### User-restricted access
88+
89+
User-restricted access meaning an end user must be present, authenticated and authorised.
90+
91+
#### Patient access mode
92+
If the end user is a patient then you must use this access mode.
93+
94+
[Review all patient access modes](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation#patient-access-mode)
95+
96+
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).
97+
98+
Allowed vectors of trust are:
99+
- `P9.Cp.Cd`
100+
- `P9.Cp.Ck`
101+
- `P9.Cm`
102+
103+
#### Healthcare worker access mode
104+
If the end user is a healthcare worker then you must use this access mode.
105+
106+
[Review all CIS2 healthcare worker access modes](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation#healthcare-worker-access-mode)
107+
108+
### Application-restricted access
109+
110+
This API is application-restricted, meaning we authenticate the calling application but not the end user.
111+
112+
[Review all application-restricted access modes](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation#application-restricted-apis)
89113
90114
## Headers
91115
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.
@@ -162,6 +186,11 @@ paths:
162186
163187
For the most part demographics information doesn't need to be provided in the access request since it can be pulled from PDS.
164188
189+
## Access modes
190+
191+
This endpoint supports the following access modes:
192+
- Patient access
193+
165194
## Sandbox test scenarios
166195
167196
| Scenario | Request | Response |
@@ -267,6 +296,12 @@ paths:
267296
A valid reference code must be provided as a query parameter. This reference code is returned
268297
when a QuestionnaireResponse is initially submitted via the POST endpoint.
269298
299+
## Access modes
300+
301+
This endpoint supports the following access modes:
302+
- Patient access
303+
- Healthcare worker access
304+
270305
## Sandbox test scenarios
271306
272307
| Scenario | Request | Response |
@@ -356,6 +391,12 @@ paths:
356391
357392
You can (optionally) include the `_include=RelatedPerson:patient` request parameter to include the patient's details in the response.
358393
394+
## Access modes
395+
396+
This endpoint supports the following access modes:
397+
- Patient access
398+
- Healthcare worker access
399+
359400
## Sandbox test scenarios
360401
361402
| Scenario | Request | Response |
@@ -475,6 +516,13 @@ paths:
475516
476517
You can (optionally) include the `_include=Consent:patient` request parameter to include the patient's details in the response.
477518
519+
## Access modes
520+
521+
This endpoint supports the following access modes:
522+
- Patient access
523+
- Healthcare worker access
524+
- Application-restricted access
525+
478526
## Sandbox test scenarios
479527
480528
| Scenario | Request | Response |
@@ -618,6 +666,11 @@ paths:
618666
## Overview
619667
Use this endpoint to create a new proxy role between a patient and a related person (proxy).
620668
669+
## Access modes
670+
671+
This endpoint supports the following access modes:
672+
- Healthcare worker access
673+
621674
## Sandbox test scenarios
622675
623676
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`.
@@ -744,6 +797,11 @@ paths:
744797
745798
You can (optionally) include the `_include=Consent:patient` request parameter to include the patient's details in the response.
746799
800+
## Access modes
801+
802+
This endpoint supports the following access modes:
803+
- Healthcare worker access
804+
747805
## Sandbox test scenarios
748806
749807
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.
@@ -857,6 +915,12 @@ paths:
857915
* JSON Patch operations must be valid according to RFC 6902
858916
* Status changes must use valid status codes from <http://hl7.org/fhir/consent-state-codes>
859917
918+
## Access modes
919+
920+
This endpoint supports the following access modes:
921+
- Patient access
922+
- Healthcare worker access
923+
860924
## Sandbox test scenarios
861925
The sandbox supports a limited number of scenarios, and does not attempt to validate requests. The returned response is dependant on the `id` parameters.
862926

0 commit comments

Comments
 (0)