Search loading...


Explore and Make use of Nationally Defined Messaging APIs


Cross organisation audit and provenance

Overview of how audit and provenance data is expected to be transported over the GP Connect FHIR interfaces.

Cross organisation audit and provenance


Provider systems MUST ensure that access to confidential data, including patient or clinical data, through the API must meet, as a minimum, the same requirements for information governance, authentication and authorisation, and auditing as that of the host system the API exposes.

Audit trail

For implementers that don’t have access to the GP SoC Framework / ‘IG Requirements for GP Systems V4’ requirements then the following extract of requirements covers the main audit trail requirements:

Provider systems MUST record in an audit trail all access and data changes within the system as a result of API activity in the same way that internal access and changes are required to be recorded.

Provider systems MUST ensure that all API transactions are recorded in an audit trail, and that audit trails must be subject to the standard IG audit requirements as defined in “IG Requirements for GP Systems V4” or as subsequently amended.

Provider systems MUST ensure failed or rejected API transactions are recorded with the same detail as for successful API requests, with error codes as per the error handling guidance.

Audit trail records MUST include the following minimum information:

  • a record of the user identity. This is the User ID, Name, Role profile (including Role and Organisation, URP id when Smartcard authenticated) attribute values, obtained from the user’s Session structure
  • a record of the identity of the authority – the person authorising the entry of, or access to data (if different from the user)
  • the date and time on which the event occurred
  • details of the nature of the audited event and the identity of the associated data (e.g. patient ID, message ID) of the audited event;
  • a sequence number to protect against malicious attempts to subvert the audit trail by, for example, altering the system date
  • audit trail records should include details of the end-user device (or system) involved in the recorded activity

Audit trails MUST be enabled at all times and there MUST NOT be means for users, or any other individuals, to disable any Audit Trail.


Provider systems MUST ensure that all additions, amendments or logical deletions to administrative and clinical data made via an API is clearly identified with information regarding the provenance of the data (e.g. timestamp, details of Consumer system, details of user (including role), so it is clear which information has been generated through an API rather than through the Provider system itself.

Provider systems MUST record the following provenance details of all API personal and sensitive personal data recorded within the system:

  • author details (identified through unique ID), including name and role
  • data entered by (if different from author)
  • date & time (to the second) entered
  • originating organisation
  • API interaction

Provider systems MUST ensure that data provided to Consumer systems only include data for which the GP practice acts as Data Controller.

Patient dissent

Provider systems MUST ensure that Patient Consent is respected (i.e. where express dissent is recorded then data is not shared).

Cross organisation audit and provenance transport

Bearer token

Consumer systems MUST provide audit and provenance details in the HTTP authorization header as an oAuth Bearer Token (as outlined in RFC 6749) in the form of a JSON Web Token (JWT) as defined in RFC 7519.

An example such an HTTP header is given below:

     Authorization: Bearer jwt_token_string

Provider systems MUST respond to oAuth Bearer Token errors in line with RFC 6750 - section 3.1.

JSON Web Tokens (JWT)

  • Consumer system MUST generate a new JWT for each API request containing the claims outlined in the table below
  • Where the claim contains a FHIR resource the FHIR resource should conform to the GP Connect FHIR resource profiles outlined on the FHIR Resources page
    • An exception to this requirement is that in the requesting_practitioner claim the Practitioner resource should contain an identifier with the system " rather than the system required by the resource profile This is required as there was an error during testing and assurance which resulted in the providers validate that the identifier in the resource has the incorrect value, so for consumers to make a successful call the incorrect system value needs to be included.
Claim Priority Description Fixed Value Dynamic Value
iss R Requesting systems issuer URI No Yes
sub R ID for the user on whose behalf this request is being made. Matches No Yes
aud R Authorization server’s token_URL No
exp R Expiration time integer after which this authorization MUST be considered invalid. exp (now + 5 minutes) UTC time in seconds
iat R The UTC time the JWT was created by the requesting system iat now UTC time in seconds
reason_for_request R Purpose for which access is being requested directcare No
requested_record R The FHIR patient resource being requested (i.e. NHS Number identifier details) No FHIR Patient1
FHIR Organization2
requested_scope R Data being requested2 patient/*.[read|write]
requesting_device R FHIR device resource making the request No FHIR Device1
requesting_organization R FHIR organisation resource making the request No FHIR Organization1+4
requesting_practitioner R FHIR practitioner resource making the request No FHIR Practitioner1+3

1 Minimal FHIR resource to include any relevant business identifier(s).

2 Patient scope for patient centric APIs (i.e. Get Care Record and Patient’s Appointments, Patient Task) or scope for organisation centric APIs (i.e. Get Organization Schedule)

3 To contain the practitioners local system identifier(s) (i.e. login details / username). Where the user has both a local system ‘role’ as well as a nationally-recognised role, then the latter MUST be provided. Default usernames (for example, referring to systems or groups) MUST NOT be used in this field.

4 The requesting organisation resource MUST refer to the care organisation from where the request originates rather than any other organisation which may host hardware or software, route requests to Spine, and/or hold the endpoint registration.

JWT generation

Consumer systems MUST generate the JSON Web Token (JWT) consisting of three parts separated by dots (.), which are:

  • header
  • payload
  • signature

Consumer systems MUST generate an Unsecured JSON Web Token (JWT) using the “none” algorithm parameter in the header to indicate that no digital signature or MAC has been performed (please refer to section 3.6 of RFC 7513 for details).

  "alg": "none",
  "typ": "JWT"

Consumer systems MUST generate an empty signature.

The final output is three base64url encoded strings separated by dots.

For example:


JWT payload example

	"iss": "https://[ConsumerSystemURL]",
	"sub": "[PractitionerID]",
	"aud": "",
	"exp": 1469436987,
	"iat": 1469436687,
	"reason_for_request": "directcare",
	"requested_record": {
		"resourceType": "Patient",
		"identifier": [{
			"system": "",
			"value": "[NHSNumber]"
	"requesting_device": {
		"resourceType": "Device",
		"id": "[DeviceID]",
		"identifier": [{
			"system": "[DeviceSystem]",
			"value": "[DeviceID]"
		"model": "[SoftwareName]",
		"version": "[SoftwareVersion]"
	"requesting_organization": {
		"resourceType": "Organization",
		"id": "[OrganizationID]",
		"identifier": [{
			"system": "",
			"value": "[ODSCode]"
		"name": "Requesting Organisation Name"
	"requesting_practitioner": {
		"resourceType": "Practitioner",
		"id": "[PractitionerID]",
		"identifier": [{
			"system": "",
			"value": "[SDSUserID]"
			"system": "[UserSystem]",
			"value": "[UserID]"
		"name": {
			"family": ["[Family]"],
			"given": ["[Given]"],
			"prefix": ["[Prefix]"]
		"practitionerRole": [{
			"role": {
				"coding": [{
					"system": "",
					"code": "[SDSJobRoleName]"

Where the Practitioner has both a local system role as well as a Spine RBAC role, then the Spine RBAC role MUST be supplied

Example code


External documents/policy documents

Name Author Version Updated
GPSoC IG Requirements for GP Systems NHS Digital v4.0 19/09/2014
GP Systems Interface Mechanism Requirements V 1 NHS Digital v0.10  
Tags: integration

All content is available under the Open Government Licence v3.0, except where otherwise stated