Search loading...

API Hub

Explore and Make use of Nationally Defined Messaging APIs

 

JSON Web Token Guidance

JSON Web Token implementation guidance for developers.

The JSON Web Token (JWT) is required for interaction with both the NRL and SSP and MUST meet the requirements outlined on this page.

Format

The JWT MUST:

  • be included in the standard HTTP Authorization request header.
  • conform to the Spine JWT definition, taking note of the validation of claims extended by the rules defined on this page. Where there is a difference between the requirements and validation specified in the Spine Core specification and on this page, the requirements on this page take precedence.

Claims

For all requests the following claim requirements MUST be met:

Claim Requirement
requesting_organisation The ODS code of the requesting organisation MUST be known to the Spine and be in the form:

https://fhir.nhs.uk/Id/ods-organization-code|[odsCode]
requesting_system The ASID of the requesting system (associated with the ODS code in the requesting_organisation claim) MUST be known to Spine and be in the form:

https://fhir.nhs.uk/Id/accredited-system|[ASID]
scope For requests to the NRL: scope MUST have the value patient/DocumentReference.read (consumer interactions) or patient/DocumentReference.write (provider interactions).

For requests to the SSP (see SSP Information Retrieval Interaction): scope MUST have the value patient/*.read (consumer interactions) or patient/*.write (provider interactions).

Healthcare Professional Access

Where a consuming system is making a request on behalf of a healthcare professional, the following claim requirements MUST be met:

Claim Requirement
requesting_user The claim MUST be populated with the requesting user details in the form:

https://fhir.nhs.uk/Id/sds-role-profile-id|[sds_role_profile_id]
sub The value MUST match the value of the requesting_user claim.
reason_for_request Fixed value: directcare
requesting_patient The claim MUST NOT be included.

Example: Healthcare professional access

{
  "iss": "https://cas.nhs.uk",
  "sub": "https://fhir.nhs.uk/Id/sds-role-profile-id|4387293874928",
  "aud": "https://clinicals.spineservices.nhs.uk",
  "exp": 1469436987,
  "iat": 1469436687,
  "reason_for_request": "directcare",
  "scope": "patient/Documentreference.read",
  "requesting_system": "https://fhir.nhs.uk/Id/accredited-system|200000000205",
  "requesting_organisation": "https://fhir.nhs.uk/Id/ods-organization-code|RXA",
  "requesting_user": "https://fhir.nhs.uk/Id/sds-role-profile-id|4387293874928"
}

Unattended Access

For Provider interactions only. Where an interaction is performed without a user being present, the following claim requirements MUST be met:

Claim Requirement
sub The value MUST match the value of the requesting_system claim.
reason_for_request Fixed value: directcare
requesting_user The claim MUST NOT be included.
requesting_patient The claim MUST NOT be included.

Example: Unattended access

{
  "iss": "https://cas.nhs.uk",
  "sub": "https://fhir.nhs.uk/Id/accredited-system|200000000205",
  "aud": "https://clinicals.spineservices.nhs.uk",
  "exp": 1469436987,
  "iat": 1469436687,
  "reason_for_request": "directcare",
  "scope": "patient/Documentreference.read",
  "requesting_organisation": "https://fhir.nhs.uk/Id/ods-organization-code|RXA",
  "requesting_system": "https://fhir.nhs.uk/Id/accredited-system|200000000205"
}

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