OAuth 2.0


Authentication and authorisation in both our Custom REST API and FHIR® 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:
  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 a bearer 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, 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

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.

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 duration versus session duration

There are two durations associated with a Client ID.

The token duration is the length of time for which an access token will work, before a new one must be obtained using a refresh token. This is always set to 10 minutes.

The session duration is the length of time for which you can keep obtaining new access tokens, before the user (patient, professional, team coordinator) must manually re-enter their credentials to generate a new refresh token for your Client ID. Once the session has started (i.e. by user granting access) it will expire after the session duration setting, regardless of how many refresh tokens are requested in the meantime. If you have requested a System Client ID and the integration is based on a system to system interaction with no typical ongoing user authentication then it is advisable to request a non-expiring session. This will avoid the need for the team coordinator to continually grant access after the session expires.