OAuth 2.0

Overview

Authentication and authorisation in both our Custom REST API and FHIR® REST API are through OAuth 2.0 (a widely adopted secure authorisation standard utilised by industry leaders like Google, Microsoft or Epic Systems, enabling controlled resource access without credential exposure).

The full OAuth 2.0 spec is here, in two parts:

1. The OAuth 2.0 Authorization Framework

2. The OAuth 2.0 Authorization Framework: Bearer Token Usage

Obtaining a Client ID

In order to interact with these APIs, we'll first need to issue you with a Client ID.

Please see here for details on how to request one.

Obtaining an access token

Once your interface has been configured (i.e. you have been issued with a Client ID), you'll need to obtain an access token to interact with our APIs.

If you have a User Client ID, then you'll need to follow the Authorization Code Grant workflow to get an access token.

If you have a System Client ID or a Customer System Client ID, then you'll need to follow the Client Credentials Grant workflow to get an access token.

If you have an older Tethered-Token System Client ID, then you'll need a Team Coordinator to grant you access from the web interface.

Calling the API

Bearer token

Once you have your access token, you need to prepend it with "Bearer " (note the trailing space), and then provide it in the Authorization HTTP header when making calls against the APIs.

You need to provide your access token in this way regardless of which type of client you are using.

Here is an example call taken from our FHIR documentation, which shows how to use curl to search for a Patient with NHS number 9999999999, assuming you have been granted an access token of aaaaa-bbbbb.

curl -X GET --header "Accept: application/fhir+json" --header "Authorization: Bearer aaaaa-bbbbb" "https://sandbox.patientsknowbest.com/fhir/Patient?identifier=https://fhir.nhs.uk/Id/nhs-number|9999999999"

Token expiry

An access token has a finite lifetime. The number of seconds for which it is valid is indicated by the "expires_in" parameter contained in the response to your token request. This is known as the token duration. Typically, this is 1 hour for System Clients, 5 minutes for Customer System Clients, and 10 minutes otherwise.

The session duration is the length of time for which you can keep obtaining new access tokens, using the refresh token, before the granting user must manually re-enter their credentials to renew their grant. Once the session has started (i.e. by the user granting access) it will expire after the session duration, regardless of how many refresh tokens are requested in the meantime. Note that it is possible to set a non-expiring session if that is appropriate for your particular integration. There is no concept of a session for System Clients or Customer System Clients; the Client Credentials Grant workflow will issue an access token but no refresh token.

The table below summarises these scenarios.

X-Org-Public-Id

System Client IDs are used by partners to interact with the PKB Facade and Messaging FHIR APIs on behalf of existing PKB organisations that have chosen to grant access.

If you are using a System Client ID, then when you call one of the supported API endpoints you must indicate which PKB organisation you are making the call for. The way to do this is to provide the organisation's UUID as the value for a custom HTTP header called X-Org-Public-Id.

The UUID will be given to you during setup.

Here is an example call taken from our FHIR documentation, which shows how to use curl to check whether a document 97a25402-622b-47e0-b650-bbbd08de4daf belonging to org 235a397b-1ae8-4755-9c77-1a0e2fbc5314 has been read by the patient, assuming you have been granted an access token of aaaaa-bbbbb.

curl -X POST --header "Accept: application/fhir+json" --header "Content-Type: application/fhir+json" --header "Authorization: Bearer aaaaa-bbbbb" --header "X-Org-Public-Id: 235a397b-1ae8-4755-9c77-1a0e2fbc5314" "https://sandbox.patientsknowbest.com/fhir/DocumentReference/$read-receipt-query" --data "{ \"resourceType\": \"Parameters\", \"parameter\": [ { \"name\": \"documentIdentifier\", \"valueString\": \"97a25402-622b-47e0-b650-bbbd08de4daf\" } ] }"

Open