NPA-5116 Add Generic Authorisation Documentation

Author: JackPlowman

specification/validated-relationships-service-api.yaml

@@ -72,20 +72,41 @@ info:
 
     For more details see [Network access for APIs](https://digital.nhs.uk/developer/guides-and-documentation/network-access-for-apis).
 
-    ## Security and authorisation
+    ## Access Modes
 
-    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 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)
+    - [User-restricted access](#user-restricted-access) meaning an end user must be present, authenticated and authorised.
+    - [Application-restricted access](#application-restricted-access) meaning we authenticate the calling application but not the end user
 
-    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 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.