Overview
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.
The full OAuth 2.0 spec is here, in two parts:
Obtaining a Client ID
In order to interact with these APIs, we'll first need to issue you with a Client ID.
Pleasesee 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 theAuthorization Code Grant workflow to get an access token.
If you have a System Client ID, then you'll need to follow theClient Credentials Grant workflow to get an access token.
If you have an older Tethered-Token System Client ID, then you'll need aTeam 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 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, and is always 1 hour for 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; the Client Credentials Grant workflow will issue an access token but no refresh token.
The table below summarises these scenarios.
Access token lifetime | Detecting expired access token: | Detecting expired access token: | Session lifetime | Detecting expired session: | Detecting expired session: | |
User Client | 10 minutes | The "errorMessage" string in the returned JSON begins with "access token has expired;" | Error code : | Configured for your integration | HTTP 401 | Error code : |
Tethered-Token System Client | 10 minutes | The "errorMessage" string in the returned JSON begins with "access token has expired;" | Error code : | Configured for your integration | HTTP 401 | Error code : |
System Client | 1 hour | N/A; system clients cannot call the custom REST API | HTTP 401 | N/A; refresh tokens are not issued to system clients | N/A; refresh tokens are not issued to system clients | N/A; refresh tokens are not issued to system clients |
X-Org-Public-Id
System Client IDs are used by partners to interact with the PKB 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 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\" } ] }"
PKB customer sites:deploy |developer |information governance |procurement |manual
©Patients Know Best, Ltd. Registered in England and Wales Number: 6517382. VAT Number: GB 944 9739 67.
This API specification and design is licensed under aCreative Commons Attribution 4.0 International License.