Overview of audit and provenance requirements for data transported over NRL interfaces.

Overview

Consumers and providers are required to keep an audit trail of requests to and responses from the NRL API interfaces.

  • Consumers MUST keep an audit trail of requests to and responses from the NRL.
  • Providers MUST keep an audit trail of requests to and responses from the NRL.

In addition, the NRL 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.

Access Tokens (JWT)

Consumers and providers MUST generate and supply a JWT access token with each request they initiate using the standard Authorization HTTP header, for audit purposes. Details of these requirements can be found on the JSON Web Token Guidance page.

Any request to the NRL that does not supply an Authorization HTTP header conforming to these requirements will be rejected.

Audit Logs

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.

Provider Pointer Maintenance

Providers MUST record the following in audit logs for each NRL maintenance interaction (POST, PATCH, DELETE):

For requests to the NRL For responses from the NRL
ASID
HTTP Request Body (for POST and PATCH only)
HTTP Request URL
HTTP Verb
ODS Code
NHS Number
Request Datetime
User ID (if supplied)
HTTP Response Body
HTTP Status Code
Pointer Logical ID
Response Datetime

Consumer Pointer Search/Read

Consumers MUST record the following in audit logs for each NRL search interaction (GET):

For requests to the NRL For responses from the NRL
ASID
HTTP Request URL
HTTP Verb
ODS Code
NHS Number
Request Datetime
User ID
HTTP Response Body
HTTP Status Code
Response Datetime

Audit Log Attributes

The following table details the audit log attributes and the source of the value for the attribute.

Attribute Source
ASID requesting_system from JWT (only the ASID portion is required, for example, https://fhir.nhs.uk/Id/accredited-system\|[ASID]).
HTTP Request Body HTTP request body (where applicable, i.e. POST or PATCH).
HTTP Request URL For example, the URL of the NRL service that was called.
HTTP Response Body Response message.
HTTP Status Code Describes the response outcome (Success: 2xx | Fail: 4xx or 5xx).
HTTP Verb POST, PATCH, GET or DELETE.
NHS Number This is the value used as part of the pointer subject reference (for example, https://demographics.spineservices.nhs.uk/STU3/Patient/[nhsNumber]) which may be an attribute on the pointer or a search query parameter depending on the action being performed.
ODS Code requesting_organization from JWT (only the ODSCode portion is required, for example, https://fhir.nhs.uk/Id/ods-organization-code\|[odsCode]).
Pointer Logical ID The logical ID of the pointer generated by the NRL, contained in the Location response header.
Request Datetime Datetime that audit log was written.
Response Datetime Datetime that the response was received from NHS Digital service.
User ID requesting_user from JWT

This is not mandatory where the request is completed as a non-interactive process.

Requesting an Audit Trail

Providers can request the following two types of audit trail data from NHS Digital:

  • All audit trails for a given patient (identified by their NHS number).
  • All audit trails for all pointers owned by the provider.

In either case, the provider is permitted to view audit trail information only for pointers that it owns and maintains.