NPA-5880: Improved docs for postman and script readme

Author: ClarksonAdam

postman/validated_relationship_service.integration.postman_collection.json

@@ -2,7 +2,7 @@
 	"info": {
 		"_postman_id": "c3ee07a1-47e5-43f7-96f9-5e56d403af45",
 		"name": "Validated Relationship Service - Integration",
-		"description": "## About the collection\n\nThe collection has been organised by API endpoint - you will find a folder for each one.\n\nWithin those endpoints are requests covering success and error response scenarios.\n\nEach request has at least 1 example against it. This shows the expected response for that request. Some requests have multiple examples showing how the response differs when different parameters are provided.\n\n### Authorization types\n\nWhen you send a request to the Validated Relationship Service, your request will first be authorised by the API Management service (APIM).\n\nThe Validated Relationship Service has 3 types of authorization:\n\n- CIS2 - For healthcare practitioners\n    \n- App-restricted - for service-to-service authorization\n    \n- Login - For patient/proxy access via the NHS App\n    \n\nEach VRS API endpoint uses a different combination of these auth types depending on their use case.\n\nYou will need to follow the steps in the 'Getting Started' section below to set the correct authorization tokens for each of these types.\n\nPlease see the folder-level docs for each endpoint for details about what auth types are available to use.\n\n## Getting started\n\n### Environment variables\n\nYou will need to add the following environment variables to the collection.\n\n#### `cis2_token`\n\nAuthorization token value for CIS2 (healthcare practitioner access).\n\n_Only required when using endponts that require this auth method._\n\nThis value can be generated by running the `get_cis2_access_token_int.py` script . See more details in the 'How to create a valid Authorization header' section below.\n\n#### `login_token`\n\nAuthorization token value for NHS Login (patient access).\n\n_Only required when using endponts that require this auth method._\n\nThis value can be generated by running the `get_nhs_login_access_token_int.py` script . See more details in the 'How to create a valid Authorization header' section below.\n\n#### `vrs_api_private_key`\n\n**(This is not the same as the private key in the NHS Developer Account portal.)**\n\nAPI private key for the Validated Relationship Service integration application.\n\n_Only required when using endponts that use the app restricted auth method._\n\nThis value can be copied from the /main/vrs-app-credentials-{id} secret in **AWS Secrets Manager** or requested to be sent securely from a member of the VRS team.\n\n#### `nhs_developer_account_api_key`\n\nAPI app key for the Validated Relationship Service integration application.\n\n_Only required when using endponts that use the app restricted auth method._\n\nThis value can be copied from the NHS - Proxy Core Services - Integration environment resource in the NHS Developer Account portal.\n\n#### `consent_app_auth_header_value` (Generated automatically)\n\nAuthorization token value for app restricted auth.\n\n_Only required when using endponts that use the app restricted auth method._\n\n**You do not need to change this value as it is automatically set in the pre-request script.**\n\n#### `tpp_9674998535_access_token`, `tpp_9674998454_access_token`, `emis_9692113698_access_token,` and `emis_9692113612_access_token`\n\nAuthorization token value for connecting to GPIT supplier systems in NAM tests (Get proxy roles only).\n\n_Only required when running the_ `_Get proxy roles (GET/Consent) Valid request - NAM - Get proxy roles_` _requests._\n\nValues for these environment variables can be found on the [Test data page in Confluence](https://nhsd-confluence.digital.nhs.uk/spaces/NPA/pages/950553445/Test+data+and+accounts+repository+-+NPA#TestdataandaccountsrepositoryNPA-GPITtestaccountsforEXT).\n\n### How to create a valid Authorization header\n\n#### Manually through Python scripts (required for Login and CIS2)\n\n##### Pre-requisites\n\nAccess the token generation scripts from the [validated-relationships-service-api repo](https://github.com/NHSDigital/validated-relationships-service-api/tree/master/scripts):\n\n- get_app_access_token_int.py - for app restricted authorization\n    \n- get_cis2_access_token_int.py - for CIS2 authorization\n    \n- get_nhs_login_access_token_int.py - for Login user authorization\n    \n\nSee the [README](https://github.com/NHSDigital/validated-relationships-service-api/tree/master/scripts/README.md) for information about how to run them and what environment variables are needed.\n\n##### Steps\n\n1. Generate bearer tokens for each of the above methods using the provided scripts\n    \n2. Go to the Authorization tab for this Postman request\n    \n3. Select 'Bearer token' from the drop-down\n    \n4. Add the generated bearer token value (**without** the 'bearer' keyword before it) into the Token field\n    \n\nTokens expire every 5 minutes. Once expired, you will receive an 'Unauthorised' response from the API endpoints. At this point, a new token will need to be generated by repeating the above steps.\n\n#### Automatically through pre-request script (for App-restricted)\n\nA pre-request script has been added to the endpoints where app-restricted auth can be used to obtain app-restricted tokens automatically. For this to work, you will need to add values for the following environment variables:\n\n- `private_key`\n    \n- `api_key`\n    \n\nIf those values are set and valid, then no further action is required.\n\n## Running a request\n\nOnce you have completed the above 'Getting Started' steps you will be able to send requests by either clicking the 'Send' button on each request, or the 'Try' button on each example.\n\nThe pre-prod environments are not constricted to just the requests provided in this collection. Feel free to change and create requests/examples as you require. However, only the test users provided will work in these environments.\n\n## Test data\n\nAll of the requests in the collection use test data and users that have been set up to demonstrate each specific scenario. No sensitive data is stored in this collection.\n\nSee each scenario for information about what test users are being used.",
+		"description": "## About the collection\n\nThe collection has been organised by API endpoint - you will find a folder for each one.\n\nWithin those endpoints are requests covering success and error response scenarios.\n\nEach request has at least 1 example against it. This shows the expected response for that request. Some requests have multiple examples showing how the response differs when different parameters are provided.\n\n### Authorization types\n\nWhen you send a request to the Validated Relationship Service, your request will first be authorised by the API Management service (APIM).\n\nThe Validated Relationship Service has 3 types of authorization:\n\n- CIS2 - For healthcare practitioners\n    \n- App-restricted - for service-to-service authorization\n    \n- Login - For patient/proxy access via the NHS App\n    \n\nEach VRS API endpoint uses a different combination of these auth types depending on their use case.\n\nYou will need to follow the steps in the 'Getting Started' section below to set the correct authorization tokens for each of these types.\n\nPlease see the folder-level docs for each endpoint for details about what auth types are available to use.\n\n## Getting started\n\n### Environment variables\n\nYou will need to add the following environment variables to the collection.\n\n#### `cis2_token`\n\nAuthorization token value for CIS2 (healthcare practitioner access).\n\n_Only required when using endponts that require this auth method._\n\nThis value can be generated by running the `get_cis2_access_token_int.py` script . See more details in the 'How to create a valid Authorization header' section below.\n\n#### `login_token`\n\nAuthorization token value for NHS Login (patient access).\n\n_Only required when using endponts that require this auth method._\n\nThis value can be generated by running the `get_nhs_login_access_token_int.py` script . See more details in the 'How to create a valid Authorization header' section below.\n\n#### `vrs_api_private_key`\n\n**(This is not the same as the private key in the NHS Developer Account portal.)**\n\nAPI private key for the Validated Relationship Service integration application.\n\n_Only required when using endponts that use the app restricted auth method._\n\nThis value can be copied from the /main/vrs-app-credentials-{id} secret in **AWS Secrets Manager** or requested to be sent securely from a member of the VRS team.\n\n#### `nhs_developer_account_api_key`\n\nAPI app key for the Validated Relationship Service integration application.\n\n_Only required when using endponts that use the app restricted auth method._\n\nThis value can be copied from the NHS - Proxy Core Services - Integration environment resource in the NHS Developer Account portal.\n\n#### `consent_app_auth_header_value` (Generated automatically)\n\nAuthorization token value for app restricted auth.\n\n_Only required when using endponts that use the app restricted auth method._\n\n**You do not need to change this value as it is automatically set in the pre-request script.**\n\n#### `tpp_9674998535_access_token`, `tpp_9674998454_access_token`, `emis_9692113698_access_token,` and `emis_9692113612_access_token`\n\nAuthorization token value for connecting to GPIT supplier systems in NAM tests (Get proxy roles only).\n\n_Only required when running the_ `_Get proxy roles (GET/Consent) Valid request - NAM - Get proxy roles_` _requests._\n\nValues for these environment variables can be found on the [Test data page in Confluence](https://nhsd-confluence.digital.nhs.uk/spaces/NPA/pages/950553445/Test+data+and+accounts+repository+-+NPA#TestdataandaccountsrepositoryNPA-GPITtestaccountsforEXT).\n\n### How to create a valid Authorization header\n\n#### Manually through Python scripts (required for Login and CIS2)\n\n##### Pre-requisites\n\nAccess the token generation scripts from the [validated-relationships-service-api repo](https://github.com/NHSDigital/validated-relationships-service-api/tree/master/scripts):\n\n- get_app_access_token_int.py - for app restricted authorization\n    \n- get_cis2_access_token_int.py - for CIS2 authorization\n    \n- get_nhs_login_access_token_int.py - for Login user authorization\n    \n\nSee the [README](https://github.com/NHSDigital/validated-relationships-service-api/tree/master/scripts/README.md) for information about how to run them and what environment variables are needed.\n\n##### Steps\n\n1. Generate bearer tokens for each of the above methods using the provided scripts\n    \n2. Go to the Authorization tab for this Postman request\n    \n3. Select 'Bearer token' from the drop-down\n    \n4. Copy just the 'access_request' value from the script output into the Token field. You do **not** need to add the word 'bearer' before the value.\n    \n\nTokens expire every 5 minutes. Once expired, you will receive an 'Unauthorised' response from the API endpoints. At this point, a new token will need to be generated by repeating the above steps.\n\n#### Automatically through pre-request script (for App-restricted)\n\nA pre-request script has been added to the endpoints where app-restricted auth can be used to obtain app-restricted tokens automatically. For this to work, you will need to add values for the following environment variables:\n\n- `private_key`\n    \n- `api_key`\n    \n\nIf those values are set and valid, then no further action is required.\n\n## Running a request\n\nOnce you have completed the above 'Getting Started' steps you will be able to send requests by either clicking the 'Send' button on each request, or the 'Try' button on each example.\n\nThe pre-prod environments are not constricted to just the requests provided in this collection. Feel free to change and create requests/examples as you require. However, only the test users provided will work in these environments.\n\n## Test data\n\nAll of the requests in the collection use test data and users that have been set up to demonstrate each specific scenario. No sensitive data is stored in this collection.\n\nSee each scenario for information about what test users are being used.",
 		"schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json",
 		"_exporter_id": "18067099",
 		"_collection_link": "https://www.postman.com/lunar-crescent-672573/workspace/validated-relationship-service-pre-prod-20-11-2025/collection/18067099-c3ee07a1-47e5-43f7-96f9-5e56d403af45?action=share&source=collection_link&creator=18067099"

scripts/README.md

@@ -4,7 +4,8 @@
 
 ### Install packages
 
-The tooling we use to manage our packages in poetry so this needs to be installed on your local machine in order to run the scripts.
+The tooling we use to manage our packages in poetry so this needs to be installed on your local machine in order to run
+the scripts.
 
 Then run the following command in the scripts directory
 
@@ -26,6 +27,9 @@ export APPLICATION_CLIENT_ID={application_client_id}
 export APPLICATION_CLIENT_SECRET={application_client_secret}
 ```
 
+The values for `APPLICATION_CLIENT_ID` and `APPLICATION_CLIENT_SECRET` can be found on the NHS Developer Account
+portal 'NHS - Proxy Core Services...' environment resource in the Active API keys section.
+
 #### Select an identifier
 
 There are a different levels of authenticator assurance levels eg. AAL3.
@@ -67,6 +71,9 @@ export APPLICATION_CLIENT_ID={application_client_id}
 export APPLICATION_CLIENT_SECRET={application_client_secret}
 ```
 
+The values for `APPLICATION_CLIENT_ID` and `APPLICATION_CLIENT_SECRET` can be found on the NHS Developer Account
+portal 'NHS - Proxy Core Services...' environment resource in the Active API keys section.
+
 #### Select an identifier
 
 There are a different identity proofing levels eg. p9.
@@ -98,7 +105,9 @@ e.g.
 
 ### Get App Restricted Access Token for Int Environment
 
-Application restricted authentication is when a system is trying to access an API rather than a person. For example the Validated Relationship Service (VRS) will need an app restricted access token in order to call the Personal Demographic Service (PDS) API.
+Application restricted authentication is when a system is trying to access an API rather than a person. For example the
+Validated Relationship Service (VRS) will need an app restricted access token in order to call the Personal Demographic
+Service (PDS) API.
 https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation#application-restricted-apis
 
 #### Set Environment Variables
@@ -112,7 +121,14 @@ export APPLICATION_CLIENT_KID={vrs_application_client_secret}
 export APPLICATION_CLIENT_PRIVATE_KEY={vrs_application_client_private_key}
 ```
 
-Note with VRS_CLIENT_PRIVATE_KEY it needs to be wrapped in double quotation marks otherwise there can be formatting errors
+Note with VRS_CLIENT_PRIVATE_KEY it needs to be wrapped in double quotation marks otherwise there can be formatting
+errors
+
+The values for `APPLICATION_CLIENT_ID` and `APPLICATION_CLIENT_KID` can be found on the NHS Developer Account portal '
+NHS - Proxy Core Services...' environment resource in the Active API keys section.
+
+The `APPLICATION_CLIENT_PRIVATE_KEY` is stored in AWS Secrets Manager. Please contact the VRS team if you don't have AWS
+access to obtain this.
 
 #### Run the script
 
@@ -132,7 +148,8 @@ e.g.
 
 ### Trouble Shooting
 
-If you have issues with the script, a good place to start is to ensure the environment variables are accessible to poetry. This can be achieved by installing the poetry dotenv plugin
+If you have issues with the script, a good place to start is to ensure the environment variables are accessible to
+poetry. This can be achieved by installing the poetry dotenv plugin
 
 Run this command