Information retrieval is an interaction between a consumer and a provider; routing and receiving requests via the SSP allows both parties to be ignorant of each other’s authentication and authorisation mechanisms, as the SSP handles the other side of the transaction.
The SSP is a content agnostic forward proxy, which is used to control and protect access to health systems. It provides a single security point for both authentication and authorisation for systems. See the SSP specification for more details.
End-to-End Retrieval Process
The following diagram describes how information retrieval is facilitated through the SSP using a URL included in a pointer.
The diagram above depicts the step-by-step, end-to-end, process for retrieving information, as follows:
- Consumer system queries the NRL to see if any pointers exist for the patient.
- The NRL responds with a collection of pointers containing information about the patient.
- Consumer system identifies a pointer that references information which could be of value for the provision of care.
- Consumer system takes the URL property value from that pointer and uses this value to create a request to the provider system that holds the information.
- Consumer system sends the request to the provider system via the SSP.
- The SSP performs security checks against the consumer and then provider.
- The request is forwarded onto the provider system.
- Provider system receives and validates the request.
- Provider system responds back to the SSP with the requested information, which is returned to the consumer.
- Consumer system receives the information and processes it ready to display to the end user.
Requesting Information via the SSP
Endpoints which allow retrieval of information via the SSP MUST do so with a HTTPS GET request, to the URL contained within the NRL pointer.
The provider endpoint MUST NOT require any custom parameters to be passed with the request, unless explicitly stated in the relevant format specification.
For a consumer to retrieve information via the SSP, the consumer MUST percent encode the
content.attachment.url property from the NRL pointer and prefix it with the SSP server URL as follows:
The consumer and the provider’s endpoint MUST support the following HTTP request headers:
||Consumer’s TraceID - a unique identifier provided by the consumer (i.e. GUID/UUID).|
||Consumer’s ASID - a unique identifier for the consuming system.
The consumer will be given an ASID by NHS Digital when connecting to the Spine.
Consumers MUST include the provider ASID in the
The provider ASID can be obtained through performing a Spine Directory Services (SDS) lookup. This can be done using the Information Owner ODS code, which is included in the pointer metadata, and the interaction ID
A worked example of the endpoint look-up process can be found in the Spine Core specification.
If multiple ASIDs are found for the ODS code and interaction ID, the associated FQDN can be matched to the record URL FQDN to obtain the correct ASID.
||Spine’s Interaction ID.
The interaction ID for retrieving a record referenced in an NRL pointer is a fixed value, specific to the NRL service:
For more information on the SSP required headers or full technical details, please refer to the Spine Secure Proxy Implementation Guide.
The provider endpoint MUST NOT require any custom headers to be passed with the request, unless explicitly stated in the relevant format specification.
A successful request MUST:
- return a
200OK HTTP status code.
- return a response body containing the requested information in the format described in the format metadata attribute on the pointer. See Supported Formats for more details.
A failed request:
- MUST return an error type HTTP status code (i.e. 4xx or 5xx).
- SHOULD return a response body with diagnostic details.
Authentication and Authorisation
Consumer systems MUST ensure users are authenticated and authorised, using an appropriate access control mechanism, before retrieving information.
Consumers MUST generate and supply a JWT access token with each request they initiate using the standard
Authorization HTTP header. Details of these requirements can be found on the JSON Web Token Guidance page. The JWT can be used in provider systems for auditing purposes. Providers are not required to perform any further authentication or authorisation.
More details can be found on the Security page.
Provider Retrieval Endpoints
Endpoints exposed by a provider for retrieval via the SSP must be registered on the Spine Directory Service (SDS). The requirements for registering endpoints on SDS are as follows:
- The FQDN MUST be of the form
nrl-[ODS_code].[supplier].thirdparty.nhs.uk, where the ODS code can be for the supplier or information owner organisation, depending on the deployment. Following completion of assurance, providers will be supplied with an FQDN.
- Every system MUST have a unique ASID for each organisation. For example, the same system deployed into three organisations would be represented by three unique ASIDs. See below for further details.
- All interactions with the SSP MUST be over port
- Endpoints MUST NOT include explicit port declarations (e.g.
- Endpoints MUST have been registered with the SSP retrieval interaction ID
See the Spine Core specification for further detail on registering provider endpoints.
Providers MUST ensure that the Information Owner ODS code on the pointer metadata matches the ODS code for the endpoint registered in SDS. This is required to enable consumers to perform an SDS lookup to obtain the provider ASID and populate the
Ssp-To header in the retrieval request. Each information owner requires an individual endpoint to be registered, therefore where multiple information owners expose records via a single deployment, it is recommended that the format of the endpoint is as follows:
Consumers and providers are required to keep an audit trail of requests and responses related to the retrieval of records and documents.
- Consumers MUST keep an audit trail of requests to and responses from provider systems (to retrieve records/documents etc.)
- Providers MUST keep an audit trail of requests received from consumers (to retrieve records/documents etc.) and their corresponding responses*.
* It is not necessary for a provider to keep an audit trail of the response payload returned to consumers, however, providers MUST be able to provide details of the record returned if required for medico-legal purposes.
In addition, the SSP is required to keep an audit trail of requests and responses that flow through these services and providers may request audit trail data from NHS Digital about any pointers they own/maintain.
The following sections detail what information each actor (Consumer/Provider) MUST record in their audit logs. For details of each required attribute, see the Audit Log Attributes table below.
Consumer Document/Record Retrieval
Consumers MUST record the following in audit logs for each document/record retrieval request to a provider via the SSP:
|For requests to providers||For responses from providers|
HTTP Request URL
Pointer Logical ID
|HTTP Response Body (if the request failed)
HTTP Status Code
Provider Document/Record Retrieval
Providers MUST record the following in audit logs for each record retrieval request from a consumer via the SSP:
|For requests from consumers|
HTTP Request URL
HTTP Status Code
Record version or equivalent
Audit Log Attributes
The following table details the audit log attributes and the source of the value for the attribute.
|HTTP Request URL||The URL used for the record retrieval request, which includes the value of the
|HTTP Response Body||Response message.|
|HTTP Status Code||Describes the response outcome (Success: 2xx | Fail: 4xx or 5xx).|
|NHS Number||This is the value used as part of the pointer subject reference (for example,
|Pointer Logical ID||The logical ID of the pointer (generated by the NRL) from which the retrieval request has been made.|
|Record version or equivalent||Reference to the version of the document (or equivalent) from which the NRL provider can identity what version of a record was provided.|
|Request Datetime||Datetime that audit log was written.|
|Response Datetime||Datetime that the response was received from NHS Digital service.|
|Trace ID||The consumer-generated ID of the retrieval request. This is only used for requests via the SSP and is for use in the