NHS Booking and Referral Standard

Testing and Environments

Environments

The principle environment for development and testing is the INT (integration) environment. This is a like-live environment, harnessing full security and functionality that can expect to be encountered in Production. In addition, the BaRS API specification links to the Sandbox environment, which is capable of demonstrating the key functionality but without the security overhead.

Path-to-Live has full details of all available testing environments and the functionality they offer.

TKW

What is TKW?

TKW - Toolkit Workbench - is a tool to assist development and assurance of supplier solutions to meet BaRS (Booking and Referral Standard) requirements.

The tool supports testing of key high-level workflows e.g. a booking routine, including some of asynchronous ones, but is also capable of inspecting low level technical requirements. It reports the output in Validation Reports which clearly indicates to the reader where and why a test has failed. In addition, it supports consistent error states which are often difficult to create but required for development and assurance.

The BaRS TKW tooling is embedded into the INT environment, encompassing all the same end-to-end BaRS infrastructure that is mirrored in Production, rather than being downloaded and used in isolation. This ensures the same steps to deploy solutions to Production are followed during deployment to INT, and allowing testing of requests/responses to occur under Production-like conditions. Similarly, we're able to incorporate other key components, similar to those used in Production workflows, such as the UserTest Directory of Services (DoS). In the current BaRS Applications, the TKW tool relies on values in the UserTest DoS to elicit particular behavioural responses. The Sender will populate what are termed 'sentinel' values, such as the NHSD-Target-Identifier, with a particular value and TKW will respond with a certain Capability Statement, MessageDefinition etc. (See the 'Scenarios' section for detail).

It is important for Senders to remember TKW is a stateless receiver and is not checking the relationship between requests (except in a handful of stateful scenarios - outlined below). This is important when developing workflows such as linking a booking and referral and transactional Integrity.

Using TKW Portal

Suppliers must register a Portal account to start working with TKW but Senders and Receivers will use the tool in slightly different ways due to the nature of the requests/responses they require. Senders, needing somewhere to send requests and Receivers needing something to make requests of their solution.

During the registration process, the 'Target Identifier' and 'ODS Code' values are important to ensure requests are sent and received appropriately. As a Sender (to TKW), the HTTP Header NHSD-End-User-Organisation must include the ODS Code they registered with because TKW will collate requests based on this value. When reports are downloaded and viewed, only requests with that specific ODS Code in the header will be visible. As a Receiver, once logged into the portal and selecting the request(s) TKW is required to make of your endpoint, they will be directed to the Target Identifier registered against and, equally, downloaded reports will only relate to that specific value.

Navigate to https://maitportal.testlab.nhs.uk/
Click Register and complete the form below

Email bookingandreferralstandard@nhs.net for a Target Identifier (this represents you on the Endpoint Catalogue)
MAIT Team will need enable your account, email bookingandreferralstandard@nhs.net to advise this has been created
Verify the account via email
Configure Multi-Factor Authentication
Access Portal Home screen

Sender

Once registered, requests can be made of TKW in any given workflow e.g. booking, validation etc. and the tool will record and provide downloadable validation reports for each request made.

The Scenarios (including Stateful Scenarios) outlined below highlight how to elicit particular behaviour required, note the specific sentinel values for NHSD-Target-Identifier and patient NHS Number. As a Sender, the various requests can be made and TKW will repond accoridngly.

NB: It is important for Senders to remember TKW is a stateless receiver and is not checking the relationship between requests (except in a handful of stateful scenarios - outlined below). This is important when developing workflows such as linking a booking and referral and transactional Integrity.

Receiver

A receiver can access the portal (once registered) to send either individual tests or an entire suite of tests to themselves. From the top menu bar, click 'Receive Requests' and the screen below will present -

The receiver selects the request they wish the TKW to make of their endpoint and clicks 'Execute Selected Tests' (bottom of the page). TKW will indicate when the requests have been processed.

Once all requested tests have been completed, the Validation Report can be downloaded -

from the top menu, select 'Download Reports'
then click on the button 'Download Reports' (this packages the report and makes it available to download locally)
from the top me, select 'Receiver Reports'
click on the hyperlink of the required report to download locally (.zip format)

Scenarios

The TKW will respond to the scenarios outlined below. It does not hold the state of any prior request (unless specified in the Stateful scenarios) and the specific 'sentinel' values (in bold) must be used to elicit the required response where stated.

NB: where 'Any' NHSD-Target-Identifier is specified, only those highlighted in this table will work for TKW. Any of the NHSD-Target-Identifiers configured for TKW.

Suite	Test	BaRS Application	Sentinel Element	Sentinel Value	Comment
Capability	CS for Booking and Referral receiver	111-ED	NHSD Target Identifier (HTTP Header)	2000011147	Returns CS for Booking and Referral receiver service
	CS for Referral receiver	111-ED, 999-CAS	NHSD Target Identifier (HTTP Header)	2000076289	Returns CS for Referral receiver service
	CS for Validation sender	999-CAS	NHSD Target Identifier (HTTP Header)	1374839566	Returns CS for Validation sender service (accepting interim and full validation responses)
	CS for any other receiving service	BaRS Core	NHSD Target Identifier (HTTP Header)	Any (see comment)	Any NHSD Target Identifier other than those a predefined response is set for (see above)
MessageDef	MD for Booking and Referral receiver	111-ED	context (parameter)	2000011147	Returns MD for Booking and Referral receiver service
	MD for Referral receiver	111-ED, 999-CAS	context (parameter)	2000076289	Returns MD for Referral receiver service
	MD for Validation receiver	999-CAS	context (parameter)	2000003366	Returns MD for Validation receiver service
	MD for Validation sender	999-CAS	context (parameter)	1374839566	Returns MD for Validation sender service (accepting interim and full validation responses)
	MD for any other receiving service	BaRS Core	context (parameter)	Any (see comment)	Any 'context' parameter other than those a predefined response is set for (see above)
	MD failed request - HTTP 401	BaRS Core	context (parameter)	FAIL0401
	MD failed request - HTTP 404	BaRS Core	context (parameter)	FAIL0404
	MD for invalid MessageDefs	BaRS Core	context (parameter)	2000071898	Returns invalid MessageDefintions (includes Invoice resource) for any workflow
Booking	Search for free Slots	BaRS Core	Schedule.actor:HealthcareService (parameter)	2000072489
	Search for free and busy Slots	BaRS Core	Schedule.actor:HealthcareService (parameter)	2000072489	Must include the parameter 'status=free,busy' or 'status=busy,free'
	Return no Slots	BaRS Core	Schedule.actor:HealthcareService (parameter)	2000073917
	Return mandatory Slot response	BaRS Core	Schedule.actor:HealthcareService (parameter)	1503499715	This will only include Slot, Schedule and HealthcareService
	Slot search failed request - HTTP 408	BaRS Core	Schedule.actor:HealthcareService (parameter)	2000081230	HealthcareService = 2000081230
	New booking for verified patient	BaRS Core	Patient.identifier (NHS No)	9054613556	The returned Appointment Id = ce1c4ced-2a84-4198-9982-9caf894d0bb7 in HTTP synchronous response
	Get Booking	BaRS Core	n/a		The returned Appointment Id = ce1c4ced-2a84-4198-9982-9caf894d0bb7
	Cancel Booking	BaRS Core	n/a		The returned Appointment Id = ce1c4ced-2a84-4198-9982-9caf894d0bb7 (assumed cancel is for this appointment)
	New booking for a patient with no NHS No.	BaRS Core	Patient.identifier (NHS No)	blank (no NHS No.)	The returned Appointment Id = ce1c4ced-2a84-4198-9982-9caf894d0bb7
	New booking failed request - HTTP 404	BaRS Core	Patient.identifier (NHS No)	9976150288
	New booking failed request - HTTP 409	BaRS Core	Patient.identifier (NHS No)	9933902830
	New booking failed request - HTTP 422	BaRS Core	Patient.identifier (NHS No)	9818556143
	Get booking failed request - HTTP 501	BaRS Core	n/a		GET must be for Appointment Id 0d440c22-7f25-4c6c-905d-2213d197d02a
Referral	New referral for a verified patient	111-ED, 999-CAS	Patient.identifier (NHS No)	9054613556	The returned Service Request Id = 79120f41-a431-4f08-bcc5-1e67006fcae0
	Get Referral	111-ED, 999-CAS	n/a		The returned Service Request Id = 79120f41-a431-4f08-bcc5-1e67006fcae0
	Cancel Referral	111-ED, 999-CAS	n/a		The returned Service Request Id = 79120f41-a431-4f08-bcc5-1e67006fcae0 (assumed revoke is for this Service Request)
	New referral for a patient with no NHS No.	111-ED, 999-CAS	n/a		The returned Service Request Id = 79120f41-a431-4f08-bcc5-1e67006fcae0
	New referral failed request - HTTP 400	111-ED, 999-CAS	Patient.identifier (NHS No)	9618388816	Request must be for a patient with NHS No - 9618388816 and returns 400
	New referral failed request - HTTP 500	111-ED, 999-CAS	Patient.identifier (NHS No)	9853944189	Request must be for a patient with NHS No - 9853944189 and returns 500
	Get Referral - HTTP 405	111-ED, 999-CAS	n/a		GET must be for ServiceRequest Id 61215702-0049-4d76-9807-2123f0a6ca15 and returns 405
	Get Referral - HTTP 429	111-ED, 999-CAS	n/a		GET must be for ServiceRequest Id 9d280ad9-6dda-46d2-a75e-f5b47b2f4e87 and returns 429
	Get Referral - HTTP 503	111-ED, 999-CAS	n/a		GET must be for ServiceRequest Id 4d65ddaa-4d09-41cd-87c9-aeb9c0c96352 and returns 503
Validation	New validation request	999-CAS	n/a		The validation request will return Service Request id = 0b42eac3-0175-43c8-bbab-efaa8ca31ccf
	New validation request	999-CAS	Patient.identifier (NHS No)	9945210394	The validation request will return Service Request id = 9e595424-9d67-45db-9a90-03259653cd37 which can be used in subsequent error scenarios 'Get Validation - HTTP 408' (4.6)
	New validation request	999-CAS	Patient.identifier (NHS No)	9010223337	The validation request will return Service Request id = c337e8d8-fd5b-4a13-a8e4-0f6f4ac1bb1a which can be used in subsequent error scenarios 'Get Validation - HTTP 501' (4.8)
	Get validation request	999-CAS	n/a		GET must be for Service Request id = 0b42eac3-0175-43c8-bbab-efaa8ca31ccf
	Update validation request	999-CAS	n/a		The validation request returned will be Service Request id = 0b42eac3-0175-43c8-bbab-efaa8ca31ccf
	Cancel validation request	999-CAS	n/a
	New validation failed request - HTTP 404	999-CAS	Patient.identifier (NHS No)	9976150288	Request must be for a patient with NHS No - 9976150288 and returns 404
	New validation failed request - HTTP 409	999-CAS	Patient.identifier (NHS No)	9933902830	Request must be for a patient with NHS No - 9933902830 and returns 409
	New validation failed request - HTTP 422	999-CAS	Patient.identifier (NHS No)	9818556143	Request must be for a patient with NHS No - 9818556143 and returns 422
	New validation failed request - HTTP 401	999-CAS	Patient.identifier (NHS No)	9383924314	Request must be for a patient with NHS No - 9383924314 and returns 401
	Get Validation - HTTP 408	999-CAS	n/a		GET must be for Service Request id = 0b42eac3-0175-43c8-bbab-efaa8ca31ccf and returns 408
	Get Validation - HTTP 501	999-CAS	n/a		GET must be for Service Request id = c337e8d8-fd5b-4a13-a8e4-0f6f4ac1bb1a and returns 501
Response	Full Validation Response	999-CAS	Patient.identifier (NHS No)	9091510129	Trigger a Validation response for full validation
	Interim validation response	999-CAS	Patient.identifier (NHS No)	9706161317	Trigger a Validation response for interim validation
	Safeguarding DNA Response	111-ED	Patient.identifier (NHS No)	9054613556	Accept a Response flow for failed Safeguarding
	Safeguarding DNA Response - HTTP 401	111-ED	Patient.identifier (NHS No)	9383924314	Accept a Response flow for failed Safeguarding and returns a 401

UserTest DoS Services

The sentinel values linked to UserTest DoS services can be found by searching with the following criteria.

ServiceId	Service Name	PostCode	Pathway	Comment
2000072489	TESTING ONLY BaRS Test Service (TKW)	LS1 4AP	NoseBleed without Injury	A catch-all service supporting multiple workflows. Pathways answers to obtain outcome (No, Yes, No, Yes)
2000073917	TESTING ONLY BaRS Test Service (TKW 2)	LS1 4AP	NoseBleed without Injury	Pathways answers to obtain outcome (No, Yes, No, Yes)
1503499715	TESTING ONLY BaRS Test Service (TKW 3)	LS1 4AP	NoseBleed without Injury	Pathways answers to obtain outcome (No, Yes, No, Yes)
2000081230	TESTING ONLY BaRS Test Service (TKW 4)	LS1 4AP	NoseBleed without Injury	Pathways answers to obtain outcome (No, Yes, No, Yes)
2000093816	TESTING ONLY BaRS Test Service (TKW 5)	LS1 4AP	NoseBleed without Injury	Digital Referral Roles Only. Pathways answers to obtain outcome (No, Yes, No, Yes)
1374839566	TESTING ONLY BaRS Test Service (TKW 6)	LS1 4AP	NoseBleed without Injury	Pathways answers to obtain outcome (No, Yes, No, Yes)
2000011147	TESTING ONLY BaRS Test Service (TKW 7)	LS1 4AP	NoseBleed without Injury	Pathways answers to obtain outcome (No, Yes, No, Yes)
2000076289	TESTING ONLY BaRS Test Service (TKW 8)	LS1 4AP	NoseBleed without Injury	Pathways answers to obtain outcome (No, Yes, No, Yes)
2000003366	TESTING ONLY BaRS Test Service (TKW 9)	LS1 4AP	NoseBleed without Injury	Pathways answers to obtain outcome (No, Yes, No, Yes)
2000071898	TESTING ONLY BaRS Test Service (TKW 10)	LS1 4AP	NoseBleed without Injury	Pathways answers to obtain outcome (No, Yes, No, Yes)

Stateful Scenarios

TKW supports a limited stateful response for 111 to ED requests. This is a simulation of the real-world receiving end-point and mimics the expected behaviour of a Reciever solution.

This stateful behaviour is only demonstrated for a specific patient (NHS Number 9707606312) and per NHSD-End-User-Organisation - i.e. state will be persisted only between requests made by the same End User Organisation.

Note The stateful server will reset each night which will return all users back to the initial state.

State Transition Table indicating the responses the stateful TKW scenarios will support and the expected responses-

Event	Initial State	Appointment Booked State	Referral Created State
Make a Booking	Http 200	Http 409 (Booking already exists)	Http 409 (Booking already exists)
Cancel a Booking	Http 400 (The booking this request relates to does not exist)	Http 200	Http 200
Create Linked Referral Request	Http 400 (The booking this request relates to does not exist)	Http 200	Http 409 (Referral already exists)
Create Mis-linked Referral Request	Http 400 (The booking this request relates to does not exist)	Http 409 (Referral is not linked to the correct booking)	Http 409 (Referral already exists)
Cancel Referral Request	Http 400 (The booking this request relates to does not exist)	Http 400 (No Referral - The referral this request relates to does not exist)	Http 200

Onboarding

API-M provide the security model for BaRS.

There are two roles; Sender and Receiver, and most BaRS Applications will require a solution to support both, despite being predominantly one or the other, because of the response workflow steps. In responses flows, the original Sender becomes and Receiver and original Receiver becomes a Sender.

The Sender obtains a token from the API-M platform to make requests of the BaRS API Proxy which brokers the request through the Receiver, secure via TLS-MA (Transport Layer Security-Mutual Authentication).

BaRS is based on internet-first principles and there is no requirement for Health and Social Care Network (HSCN) connectivity.

Sender

Prerequiste steps to follow -

Create Developer account
Sign in, create a team by selecting "My teams", and then "+ New Team":

Assign members to your Team
Create an App
- Owner of the App should be the Team created above
- You will need a callback URL (bottom of page)
- Enable or request the API's you wish to use for your application
  - "Booking and Referral FHIR API (Sandbox Environment)" - for Sandbox
  - "Booking and Referral FHIR API (Integration Testing Environment)" - for INT
- Generate an API Key for your application
Define your Key Identifier (KID) to be used within your JWTs
- KID Naming Convention (Development Systems) - <Supplier>-<Environment>-<rotation> i.e. MySupplier-INT-1
- KID Naming Convention (Provider Systems) - <Provider>-<Environment>-<rotation> i.e. Provider-INT-1
Generate a key pair (.pem)
- Windows based apps
- Alternatively, this website can also generate Key Pairs
Provide details to register your key
- For INT : Register Public key with API Management
  - Email - api.management@nhs.net with:
    - Environment - Sandbox, Development, Integration Test or Production
    - App ID and Name from the portal
    - Public key
      - As an attachment, PEM-Encoded
    - The KID you have defined for this public key
    - APIs you want to use
- For Production (each provider needs their own key).
  - Email -
    - Specify Live
    - App ID and Name from the portal for both Production and the INT Suppliers Development environment.
    - Public key for the providers Production instance.
      - As an attachment, PEM-Encoded.
    - The KID defined for this public key.
    - The APIs you want to use.

Generate a signed JWT using your private key

The header:

alg: The algorithm used
typ: "JWT" in this instance
kid: Your KID as provided to API Management above
example:

        {
            "alg":"RS512"
            "typ":"JWT"
            "kid":"BaRS-Sandbox-1"
        }

The payload:

iss: The API Key you generated in the portal
sub: The API Key you generated in the portal
aud: The full URL of the endpoint you are calling (example: https://sandbox.api.service.nhs.uk/oauth2/token )
jti: UUID/GUID, different for each request
exp: Epoch time, to be no more than 5 minutes in the future, indicating when your token will expire
example:

        {
            "iss":"IwrOdg62kM9LN1oFhlHAhWPHAhWPbV62",
            "sub":"IwrOdg62kM9LN1oFhlHAhWPHAhWPbV62",
            "kid":"BaRS-Sandbox-1",
            "aud":"https://sandbox.api.service.nhs.uk/oauth2/token",
            "jti":"b7ae4c12-3c04-465a-8877-c2e80f0126a3"
            "exp":"1635263528"
        }

Post your JWT to the OAuth endpoint to receive a Token

Note: A token is not required for the Sandbox environment

Your request body should be x-www-form-urlencoded with the following fields

grant_typegrant_type = "client_credentials"
client_assertion_type = "urn:ietf:params:oauth:client-assertion-type:jwt-bearer"
client_assertion = <Your signed JWT>
example:

    curl --location --request POST 'https://sandbox.api.service.nhs.uk/oauth2/token' \
    --header 'Content-Type: application/x-www-form-urlencoded' \
    --data-urlencode 'grant_type=client_credentials' \
    --data-urlencode 'client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer' \
    --data-urlencode 'client_assertion=eyJ0eXAiOiJKV1QiLCJraWQiOiJCYVJTLVNhbmRib3gtMSIsImFsZyI6IlJTNTEyIn0.
    eyJpc3MiOiJJd3JPZGc2MmtNOUxOMW9GaGw4UnlVUmJIQWhXUFY2MiIsInN1YiI6Ikl3ck9kZzYya005TE4xb0ZobDhSeVVSYkhBaFdQVjYyIiwia2lkIjoiQmFSUy1TYW5kYm94LTEiLCJhdWQiOiJodHRwczovL3NhbmRib3guYXBpLnNlcnZpY2UubmhzLnVrL29hdXRoMi90b2tlbiIsImp0aSI6IlQtWjdhTm1UODUybE1uVGtZb1NaRiIsImlhdCI6MTYzNTI2MjI2MiwibmJmIjoxNjM1MjYyMjYyLCJleHAiOjE2MzUyNjI1NjZ9.aUQSqvkzjAMRR21lNiE6YnksynPWx9wkXdEFJZ_muzGfeyuS3ooh-uXlOccQFSDS790Wrne49vMsf72NILK3iDjWyH2z8D8R_B_xYy2e3ZOktqQFNx5vZ0svC-_v1ranJKJJU8NiQog7JvRtXNwKcdExpge2bkhV2JN3bQtzPY0F7CxPohILmCIUvi3yEyr-nm3kxdB8LkifQAz132qpuO_1iENGmbqUgASYBZMTQIdD4aO8Vv9sJ9rvyIQyniw_DeY6SEMx4CHDiEb0NWmcOmpdBS1DDkuMiUohSpz8OXEYR1cZcL27dyibDJBY57FGCMBn1AVb43olYSumOIwg'

The expected success response from the Post should be a status 200 with a 3 field JSON response:

access_token: Your access token
expires_in: When it expires
token_type: "Bearer"
issued_at: Time issued
example:

        {
            'access_token': 'Sr5PGv19wTEHJdDr2wx2f7IGd0cw',
            'expires_in': '599',
            'token_type': 'Bearer'
            'issued_at': '1675784384503'
        }

A failure response will have a response code appropriate for the reason and the following 3 fields:

error: The error thrown
error_description: Diagnostics text to tell you why the error was thrown
message_id: A unique id for the interaction
example:

        {
            "error": "public_key error",
            "error_description": "You need to register a public key to use this authentication method - please contact support to configure",
            "message_id": "rrt-8923968319386160140-b-geu2-23765-558685-1"
        }

Receiver

BaRS will utilise TLS-MA to communicate with Receiving endpoints. Receiving endpoints will require a certificate under the NHS Root CA to facilitate TLS-MA.

The receiver must request a certificate under the NHS Root CA
- There are different certificate chains for INT and Prod
- INT Certificate chains
- Prod Certificate chains
The receiving endpoint will present the certificate obtained for TLS-MA
The receiving endpoint will need to trust the Root CAs and SubCAs for their respective environments
The receiving endpoint will only accept requests presented with certificates from their respective chains

As the certificates are using the NHS Root CA, FQDN must be an nhs.uk address, this is the case for both INT and Prod

You can apply for your domain here, ensuring that you complete Section 5: For website or application records visible on public internet

Once you have you have your domain registered you can then begin the process to obtain your certificate by generating a certificate request

Certificate requests will need to be signed for your endpoint. Note that the fully qualified domain (FQDN) name is equal to the certificate name (CN) by convention

At this point you should have a .key and a .csr files. The next step will be to send the .csr file to be signed by the NHS and get the client certificate. For full steps see below sections for each environment under 'Configuring endpoints for different environments'

If your client certificate will be implemented in any PTL environment then you should send the .csr file to itoc.supportdesk@nhs.net
If your client certificate will be implemented in the PROD environment then the .csr file needs to be sent to the DIR team at dir@nhs.net and they will issue the certificate after validating your request with the Live Services Pipeline at liveservices.gate@nhs.net

Integration (INT)

Request a ‘certificate only’ from ITOC
- Certificate Only (No endpoint)
- Integration environment
- Format for development systems FQDN on INT is ‘BaRS-INT-<ODS Code>.<Supplier name>.thirdparty.nhs.uk’
- Format for provider systems FQDN on INT is ‘BaRS-INT-<ODS Code>.<Provider name>.nhs.uk’
- Ensure it is clear this is a request for a ‘BaRS’ certificate
- ‘N/A’ in the Party Key section because there is no relation to SDS endpoints
- In the .csr, the ‘email’ field must be blank
Receive certificate from ITOC
Email dnsteam@nhs.net with FQDN and public facing IP to register DNS
Email bookingandreferralstandard@nhs.net with Receiver URL for BaRS/API-M to add to the Endpoint Catalogue

Production (Prod)

Once Solution Assurance issue the supplier with the Technical Conformance certificate Production endpoints can be requested
Sends .csr to dir@nhs.net, indicating this is for a BaRS Receiver endpoint
- Format for FQDN on PROD for -
  - Supplier hosted solutions is ‘BaRS-PROD-<ODS Code>.<Supplier name>.thirdparty.nhs.uk’
    - This option is used for multi-tenanted solutions.
  - Service Provider hosted solutions is ‘BaRS-PROD-<ODS Code>.<Provider name>.nhs.uk’
    - This option is used for non multi-tenanted solutions. If multiple endpoints are needed, the ODS code can be appended with an identifier for the setting.
    - It may be that the provider already has a 'nhs.uk' standard domain DNS entry, If one exists, it should be used for this new subdomain.
Receive certificate from DIR Team
Email dnsteam@nhs.net with FQDN and public facing IP to register DNS
Email bookingandreferralstandard@nhs.net with Receiver URL for BaRS/API-M to add to the Endpoint Catalogue

Note - Receiver Firewall Amendments - Requests from the BaRS API (for both INT and Prod) will originate from 34.89.0.111 & 34.89.69.6

Certificates

Introduction

The BaRS API and supplier solution will be secured by HTTPS/TLS, for both inbound and outbound connections. All certificates used are published on this website for your convenience.

In order to establish a connection to and from any environment, a chain of trust must be set up using the certificates detailed below.

For information on obtaining certificates as a Receiver see the Onboarding section.

Inbound

All inbound connections to the BaRS API will be presented with environment specific certificate, provided by Digicert. This is inline with all NHS APIs on the platform. The details for the certificate and chain used are described in the table below.

Certificate CN	Thumbprint	Parent CN	Parent Thumbprint	Environment
dev.api.service.nhs.uk	8c41b2d0080ff4f83ef4164078d17bab5ed53cbb	DigiCert TLS RSA SHA256 2020 CA1	1c58a3a8518e8759bf075b76b750d4f2df264fcd	Sandbox
int.api.service.nhs.uk	634680dfafcf3a6e229741ae7ad5b98dbe70d822	DigiCert TLS RSA SHA256 2020 CA1	1c58a3a8518e8759bf075b76b750d4f2df264fcd	INT
api.service.nhs.uk	2673f9045ba6f8ff8b7b82a9046f9b599af27cab	DigiCert TLS RSA SHA256 2020 CA1	1c58a3a8518e8759bf075b76b750d4f2df264fcd	Prod
DigiCert TLS RSA SHA256 2020 CA1	1c58a3a8518e8759bf075b76b750d4f2df264fcd	DigiCert Global Root CA	a8985d3a65e5e5c4b2d7d66d40c6dd2fb19c5436	All
DigiCert Global Root CA	a8985d3a65e5e5c4b2d7d66d40c6dd2fb19c5436	N/A	N/A	All

dev.api.service.nhs.uk (Digicert)

int.api.service.nhs.uk (Digicert)

api.service.nhs.uk (Digicert)

Outbound

All outbound connections from the BaRS API proxy to Receivers, with the exception of the Sandbox environment, will be secured using TLS-MA.

PTL

The PTL environments will present a certificate issued by the NHS PTL Root Authority, as the RootCA. This does not include the Sandbox environment.

Details of the certificate chain described in the table below can be found in the How to Connect Guidance.

Certificate CN	Thumbprint	Parent CN	Parent Thumbprint	Environment
int.api.service.nhs.uk	ce7808839f72ea8ed4548b4de37546bed5d6dc9f	NHS INT Level 1C	5007daf3aeea1c1360ec0d1e9e5bedccc7182b79	PTL
NHS INT Level 1C	5007daf3aeea1c1360ec0d1e9e5bedccc7182b79	NHS PTL Root Authority	6287fa6e10a7dd90e62556f7c2814a6abf04590c	PTL
NHS PTL Root Authority	6287fa6e10a7dd90e62556f7c2814a6abf04590c	N/A	N/A	PTL

int.api.service.nhs.uk (NHS PTL Root)

Prod

The production environment will present a certificate issued by the NHS Root Authority, as the RootCA.

Details of the certificate chain described in the table below can be found in the How to Connect Guidance

Certificate CN	Thumbprint	Parent CN	Parent Thumbprint	Environment
bars-proxy.spineservices.nhs.uk	57c911af253c2f8c362654f78f13e73051eeede3	NHS Level 1C	da3cf9d13a705704f2cba274c79794963c36ff94	Prod
NHS Level 1C	da3cf9d13a705704f2cba274c79794963c36ff94	NHS Root Authority	ec7a3b3cb795ece956c5a7bec4204a298feb236c	Prod
NHS Root Authority	ec7a3b3cb795ece956c5a7bec4204a298feb236c	N/A	N/A	Prod