Skip to content

Commit 9c8296a

Browse files
ClarksonAdamClarksonAdam
authored
NPA-5880: Pre-prod/int environment Postman collection (#273)
# Pull Request ## 🧾 Ticket Link <!-- Add the Jira ticket link here --> https://nhsd-jira.digital.nhs.uk/browse/NPA-5880 --- ## 📄 Description/Summary of Changes <!-- Describe the changes made in this PR. Include the purpose/scope/impact of the changes --> - Added Postman collection for INT - Updated OAS to include INT postman collection button - Added environment variables file for INT --- ## 🧪 Developer Testing Carried Out <!-- Describe what tests (automated/unit/manual etc.) have been done for the ticket. Include: --> <!-- - Any tests added/updated --> <!-- - Evidence that each acceptance criterion from the Jira ticket is met --> - Ran all Postman collection requests and examples --- ## 🧪 Reviewer Testing Required <!-- Describe how to test the changes that have been made in the ticket. Include: --> <!-- - Testing environment details (e.g. sandbox/local setup) --> <!-- - Steps to verify the changes --> - [ ] Check Postman requests - [ ] Review documentation around Postman collection --- ## ✅ Developer Checklist <!-- Complete before submitting the PR --> - [x] PR title follows the format: `NPA-XXXX: <short-description>` - [x] Branch name follows the convention: `<type>/NPA-XXXX/<short-description>` - [x] Commit messages follow the template: `NPA-XXXX: <short-description>` - [x] All acceptance criteria from the Jira ticket are addressed - [x] Automated tests (unit/integration/API/infrastructure etc. tests) are added or updated - [x] Assignees and appropriate labels (e.g. `terraform`, `documentation`) are added --- ## 👀 Reviewer Checklist <!-- To be completed by the reviewer --> - [ ] Changes meet the acceptance criteria of the Jira ticket - [ ] Code is able to be merged (no conflicts and adheres to coding standards) - [ ] Sufficient test evidence is provided (manual and/or automated) - [ ] Infrastructure/operational/build changes are validated (if applicable) --- ## 🚀 Post-merge <!-- Actions to complete after merging --> After merging and deploying changes to the sandbox, Postman collection or spec examples please run the Run Postman collection workflow. This will run the tests within the collection to check that the sandbox is working as expected once deployed.
1 parent 5bf8286 commit 9c8296a

11 files changed

+10217
-3
lines changed

‎postman/INT.postman_environment.json‎

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
{
2+
"id": "22fac400-f932-4ea9-8ef4-86b135cfcea0",
3+
"name": "INT",
4+
"values": [
5+
{
6+
"key": "cis2_token",
7+
"value": "",
8+
"type": "secret",
9+
"enabled": true
10+
},
11+
{
12+
"key": "login_token",
13+
"value": "",
14+
"type": "secret",
15+
"enabled": true
16+
},
17+
{
18+
"key": "api_base_url",
19+
"value": "https://int.api.service.nhs.uk/validated-relationships/FHIR/R4",
20+
"type": "default",
21+
"enabled": true
22+
},
23+
{
24+
"key": "vrs_api_private_key",
25+
"value": "",
26+
"type": "secret",
27+
"enabled": true
28+
},
29+
{
30+
"key": "nhs_developer_account_api_key",
31+
"value": "",
32+
"type": "secret",
33+
"enabled": true
34+
},
35+
{
36+
"key": "consent_app_auth_header_value",
37+
"value": "",
38+
"type": "secret",
39+
"enabled": true
40+
},
41+
{
42+
"key": "tpp_9674998535_access_token",
43+
"value": "",
44+
"type": "secret",
45+
"enabled": true
46+
},
47+
{
48+
"key": "tpp_9674998454_access_token",
49+
"value": "",
50+
"type": "secret",
51+
"enabled": true
52+
},
53+
{
54+
"key": "emis_9692113698_access_token",
55+
"value": "",
56+
"type": "secret",
57+
"enabled": true
58+
},
59+
{
60+
"key": "emis_9692113612_access_token",
61+
"value": "",
62+
"type": "secret",
63+
"enabled": true
64+
}
65+
],
66+
"color": null,
67+
"_postman_variable_scope": "environment",
68+
"_postman_exported_at": "2025-12-05T12:22:03.035Z",
69+
"_postman_exported_using": "Postman/11.74.2"
70+
}

‎postman/README.md‎

Lines changed: 13 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,18 @@
1-
# Postman Collection
1+
# Postman Collections
22

3-
This folder contains the Postman collection for the API.
3+
This folder contains the Sandbox and Integration Postman collections for the VRS API.
44

55
> [!WARNING]
66
> Documentation and links in this file are specific to the maintainers of this repository and are only available to NHS England staff.
77
8-
To update the Postman collection follow the steps on the [How to update Postman Collection Confluence page](https://nhsd-confluence.digital.nhs.uk/pages/viewpage.action?pageId=874694621)
8+
## Updating the collections
9+
10+
To update the Postman collections follow the steps on the [How to update Postman Collection Confluence page](https://nhsd-confluence.digital.nhs.uk/pages/viewpage.action?pageId=874694621)
11+
12+
## Integration collection
13+
14+
The 'integration' postman collection includes requests and examples to be used by the VRS team, consumers, and external
15+
parties to test against our INT environment.
16+
17+
For details on the environment variables and authorization methods required for this environment, please see the Getting
18+
Started section within the Postman collection itself.

‎postman/validated_relationship_service.integration.postman_collection.json‎

Lines changed: 8923 additions & 0 deletions
Large diffs are not rendered by default.

postman/Validated Relationship Service Sandbox.postman_collection.json renamed to postman/validated_relationship_service.sandbox.postman_collection.json

File renamed without changes.

‎scripts/README.md‎

Lines changed: 158 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,158 @@
1+
# How to run Scripts
2+
3+
## First Steps
4+
5+
### Install packages
6+
7+
The tooling we use to manage our packages in poetry so this needs to be installed on your local machine in order to run
8+
the scripts.
9+
10+
Then run the following command in the scripts directory
11+
12+
```
13+
poetry install
14+
```
15+
16+
## Script Specific
17+
18+
### Get CIS2 Access Token for Int Environment
19+
20+
#### Set Environment Variables
21+
22+
You will require the following environment variables in order to run the script:
23+
24+
```
25+
export APIGEE_ENVIRONMENT=int
26+
export APPLICATION_CLIENT_ID={application_client_id}
27+
export APPLICATION_CLIENT_SECRET={application_client_secret}
28+
```
29+
30+
The values for `APPLICATION_CLIENT_ID` and `APPLICATION_CLIENT_SECRET` can be found on the NHS Developer Account
31+
portal 'NHS - Proxy Core Services...' environment resource in the Active API keys section.
32+
33+
#### Select an identifier
34+
35+
There are a different levels of authenticator assurance levels eg. AAL3.
36+
For VRS CIS2 users are only accessible to access selected APIs.
37+
Please find a list of test users detailed in this page:
38+
https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation/testing-apis-with-our-mock-authorisation-service#test-users-for-cis2-authentication
39+
This can be used to select your identifier for the next step.
40+
i.e. 656005750108 to test with a CIS2 user with AAL3 authenticator assurance level.
41+
42+
#### Run the script
43+
44+
Then run the following command in the scripts directory
45+
46+
```
47+
poetry run python3 get_cis2_access_token_int.py
48+
```
49+
50+
You will be prompted to "Enter an identifier: "
51+
52+
Enter the identifier selected in previous step eg. 656005750108
53+
54+
In your terminal you should see a response that includes an access token
55+
56+
e.g.
57+
58+
```
59+
{'access_token': 'EFFs3EeT0SZbF2J14LvM93vVDTaA', 'expires_in': '599', 'refresh_token': 'BDEcXjJI36DJA8Dlw8wS0jCuYJJqC8tK', 'refresh_token_expires_in': '43199', 'refresh_count': '0', 'token_type': 'Bearer'}
60+
```
61+
62+
### Get NHS Login Access Token for Int Environment
63+
64+
#### Set Environment Variables
65+
66+
You will require the following environment variables in order to run the script:
67+
68+
```
69+
export APIGEE_ENVIRONMENT=int
70+
export APPLICATION_CLIENT_ID={application_client_id}
71+
export APPLICATION_CLIENT_SECRET={application_client_secret}
72+
```
73+
74+
The values for `APPLICATION_CLIENT_ID` and `APPLICATION_CLIENT_SECRET` can be found on the NHS Developer Account
75+
portal 'NHS - Proxy Core Services...' environment resource in the Active API keys section.
76+
77+
#### Select an identifier
78+
79+
There are a different identity proofing levels eg. p9.
80+
For VRS p9 users are only accessible to access selected APIs.
81+
Please find a list of test users detailed in this page:
82+
https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation/testing-apis-with-our-mock-authorisation-service#test-users-for-nhs-login
83+
This can be used to select your identifier for the next step.
84+
i.e. 9912003071 to test with a p9 user.
85+
86+
#### Run the script
87+
88+
Then run the following command in the scripts directory
89+
90+
```
91+
poetry run python3 get_nhs_login_access_token_int.py
92+
```
93+
94+
You will be prompted to "Enter an identifier: "
95+
96+
Enter the identifier selected in previous step eg. 9912003071
97+
98+
In your terminal you should see a response that includes an access token
99+
100+
e.g.
101+
102+
```
103+
{'access_token': 'EFFs3EeT0SZbF2J14LvM93vVDTaA', 'expires_in': '599', 'refresh_token': 'BDEcXjJI36DJA8Dlw8wS0jCuYJJqC8tK', 'refresh_token_expires_in': '43199', 'refresh_count': '0', 'token_type': 'Bearer'}
104+
```
105+
106+
### Get App Restricted Access Token for Int Environment
107+
108+
Application restricted authentication is when a system is trying to access an API rather than a person. For example the
109+
Validated Relationship Service (VRS) will need an app restricted access token in order to call the Personal Demographic
110+
Service (PDS) API.
111+
https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation#application-restricted-apis
112+
113+
#### Set Environment Variables
114+
115+
You will require the following environment variables in order to run the script:
116+
117+
```
118+
export APIGEE_ENVIRONMENT=int
119+
export APPLICATION_CLIENT_ID={vrs_application_client_id}
120+
export APPLICATION_CLIENT_KID={vrs_application_client_secret}
121+
export APPLICATION_CLIENT_PRIVATE_KEY={vrs_application_client_private_key}
122+
```
123+
124+
Note with VRS_CLIENT_PRIVATE_KEY it needs to be wrapped in double quotation marks otherwise there can be formatting
125+
errors
126+
127+
The values for `APPLICATION_CLIENT_ID` and `APPLICATION_CLIENT_KID` can be found on the NHS Developer Account portal '
128+
NHS - Proxy Core Services...' environment resource in the Active API keys section.
129+
130+
The `APPLICATION_CLIENT_PRIVATE_KEY` is stored in AWS Secrets Manager. Please contact the VRS team if you don't have AWS
131+
access to obtain this.
132+
133+
#### Run the script
134+
135+
Then run the following command in the scripts directory
136+
137+
```
138+
poetry run python3 get_app_access_token_int.py
139+
```
140+
141+
In your terminal you should see a response that includes an access token
142+
143+
e.g.
144+
145+
```
146+
{'access_token': 'EFFs3EeT0SZbF2J14LvM93vVDTaA', 'expires_in': '599', 'refresh_token': 'BDEcXjJI36DJA8Dlw8wS0jCuYJJqC8tK', 'refresh_token_expires_in': '43199', 'refresh_count': '0', 'token_type': 'Bearer'}
147+
```
148+
149+
### Trouble Shooting
150+
151+
If you have issues with the script, a good place to start is to ensure the environment variables are accessible to
152+
poetry. This can be achieved by installing the poetry dotenv plugin
153+
154+
Run this command
155+
156+
```
157+
poetry plugin add poetry-dotenv-plugin
158+
```

‎scripts/get_app_access_token_int.py‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
from os import getenv
2+
from pytest_nhsd_apim.identity_service import (
3+
ClientCredentialsConfig,
4+
ClientCredentialsAuthenticator,
5+
)
6+
7+
client_id = getenv("APPLICATION_CLIENT_ID")
8+
kid = getenv("APPLICATION_CLIENT_KID")
9+
private_key = getenv("APPLICATION_CLIENT_PRIVATE_KEY").replace("\\n", "\n")
10+
config = ClientCredentialsConfig(
11+
environment=getenv("APIGEE_ENVIRONMENT"),
12+
identity_service_base_url=f"https://{getenv('APIGEE_ENVIRONMENT')}.api.service.nhs.uk/oauth2-mock",
13+
client_id=client_id,
14+
jwt_private_key=private_key,
15+
jwt_kid=kid,
16+
)
17+
18+
authenticator = ClientCredentialsAuthenticator(config=config)
19+
print(authenticator.get_token())

‎scripts/get_cis2_access_token_int.py‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
from os import getenv
2+
from pytest_nhsd_apim.identity_service import (
3+
AuthorizationCodeConfig,
4+
AuthorizationCodeAuthenticator,
5+
)
6+
7+
identifier = str(input("Enter an identifier: "))
8+
scope = "nhs-cis2"
9+
config = AuthorizationCodeConfig(
10+
environment=getenv("APIGEE_ENVIRONMENT"),
11+
identity_service_base_url=f"https://{getenv('APIGEE_ENVIRONMENT')}.api.service.nhs.uk/oauth2-mock",
12+
callback_url="https://oauth.pstmn.io/v1/browser-callback",
13+
client_id=getenv("APPLICATION_CLIENT_ID"),
14+
client_secret=getenv("APPLICATION_CLIENT_SECRET"),
15+
scope=scope,
16+
login_form={"username": identifier},
17+
)
18+
19+
authenticator = AuthorizationCodeAuthenticator(config=config)
20+
print(authenticator.get_token())

‎scripts/get_nhs_login_access_token_int.py‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
from os import getenv
2+
from pytest_nhsd_apim.identity_service import (
3+
AuthorizationCodeConfig,
4+
AuthorizationCodeAuthenticator,
5+
)
6+
7+
identifier = str(input("Enter an identifier: "))
8+
scope = "nhs-login"
9+
config = AuthorizationCodeConfig(
10+
environment=getenv("APIGEE_ENVIRONMENT"),
11+
identity_service_base_url=f"https://{getenv('APIGEE_ENVIRONMENT')}.api.service.nhs.uk/oauth2-mock",
12+
callback_url="https://oauth.pstmn.io/v1/browser-callback",
13+
client_id=getenv("APPLICATION_CLIENT_ID"),
14+
client_secret=getenv("APPLICATION_CLIENT_SECRET"),
15+
scope=scope,
16+
login_form={"username": identifier},
17+
)
18+
19+
authenticator = AuthorizationCodeAuthenticator(config=config)
20+
print(authenticator.get_token())

0 commit comments

Comments
 (0)