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
Authorizationrequest 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_organization |
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_organization 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_organization": "https://fhir.nhs.uk/Id/ods-organization-code|RXA",
"requesting_user": "https://fhir.nhs.uk/Id/sds-role-profile-id|4387293874928"
}
Citizen Access
Where a consuming system is making a request on behalf of a citizen, the following claim requirements MUST be met:
| Claim | Requirement |
|---|---|
requesting_patient |
The claim MUST be populated with the citizen’s patient details (the subject of the information being requested) in the form:https://fhir.nhs.net/Id/nhs-number|[nhs_number]
|
sub |
The value MUST match the value of the requesting_patient claim. |
reason_for_request |
Fixed value: patientaccess
|
act |
This claim is for use where there is delegated access by one citizen on behalf of another citizen. Where the request is citizen access but not to their own record the act claim MUST be populated with the details of the requesting citizen.The claim MUST be in the form: "act": { "sub": "https://fhir.nhs.net/Id/nhs-number|[nhs_number]"}
|
requesting_user |
The claim MUST NOT be included. |
Example: Citizen accessing own record
{
"iss": "https://cas.nhs.uk",
"sub": "http://fhir.nhs.net/Id/nhs-number|6101231234",
"aud": "https://clinicals.spineservices.nhs.uk",
"exp": 1469436987,
"iat": 1469436687,
"reason_for_request": "patientaccess",
"scope": "patient/Documentreference.read",
"requesting_system": "https://fhir.nhs.uk/Id/accredited-system|200000000205",
"requesting_organization": "https://fhir.nhs.uk/Id/ods-organization-code|RXA",
"requesting_patient": "https://fhir.nhs.net/Id/nhs-number|6101231234"
}
Example: Citizen accessing another citizen’s record
{
"iss": "https://cas.nhs.uk",
"sub": "http://fhir.nhs.net/Id/nhs-number|6101231234",
"aud": "https://clinicals.spineservices.nhs.uk",
"exp": 1469436987,
"iat": 1469436687,
"reason_for_request": "patientaccess",
"scope": "patient/Documentreference.read",
"requesting_system": "https://fhir.nhs.uk/Id/accredited-system|200000000205",
"requesting_organization": "https://fhir.nhs.uk/Id/ods-organization-code|RXA",
"requesting_patient": "https://fhir.nhs.net/Id/nhs-number|6101231234",
"act": {
"sub": "https://fhir.nhs.net/Id/nhs-number|9876543210"
}
}
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_organization": "https://fhir.nhs.uk/Id/ods-organization-code|RXA",
"requesting_system": "https://fhir.nhs.uk/Id/accredited-system|200000000205"
}
