Page Comparison

...

Authentication and authorisation in both ourCustom REST API andFHIR® REST API are through OAuth 2.0, the same open standard that Facebook, Google, Twitter and Yahoo! have adopted (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.

...

If you have a User Client ID, then you'll need to follow theAuthorization 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 theClient Credentials Grant workflow to get an access token.

...

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

Here is anexample 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, and this is always 1 hour for system clientsfor 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 clientsSystem 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.

...

The UUID will be given to you during setup.

Here is anexample 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\" } ] }"

...