---
title: "OAuth 2.0"
canonical: "https://wiki.patientsknowbest.com/space/api/3365078610/OAuth%202.0"
format: markdown
---
> Macro (pagetree)



> Macro (toc)

# Overview

Authentication and authorisation in both our[ ](https://dev.patientsknowbest.com/home/rest-api)<u>[Custom REST API](https://wiki.hub.patientsknowbest.com/wiki/spaces/api/pages/3363897377)</u> and[ ](https://dev.patientsknowbest.com/home/developer-tutorial/mail-management-apis/fhir-apis)<u>[FHIR® REST API](https://pkbdev.atlassian.net/wiki/spaces/api/pages/3363602489/FHIR+APIs)</u> are through <u>[OAuth 2.0](/wiki/pages/resumedraft.action?draftId=3365078610)</u> (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. <u>[The OAuth 2.0 Authorization Framework](https://www.google.com/url?q=https%3A%2F%2Ftools.ietf.org%2Fhtml%2Frfc6749&sa=D&sntz=1&usg=AOvVaw368kvWLmvsiNl8S0r3RA3k)</u>
2. <u>[The OAuth 2.0 Authorization Framework: Bearer Token Usage](https://www.google.com/url?q=https%3A%2F%2Ftools.ietf.org%2Fhtml%2Frfc6750&sa=D&sntz=1&usg=AOvVaw3dNix5gBIsBuLMgafFb794)</u>

# Obtaining a Client ID

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

Please[ ](https://dev.patientsknowbest.com/home/oauth2/client-id)<u>[see here](https://wiki.hub.patientsknowbest.com/wiki/spaces/api/pages/3365013163)</u> 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[ ](https://dev.patientsknowbest.com/home/oauth2/authorization-code-grant)<u>[Authorization Code Grant workflow](https://wiki.hub.patientsknowbest.com/wiki/spaces/api/pages/3365013193)</u> 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[ ](https://dev.patientsknowbest.com/home/oauth2/client-credentials)<u>[Client Credentials Grant workflow](https://wiki.hub.patientsknowbest.com/wiki/spaces/api/pages/3364947437)</u> to get an access token.

If you have an older **Tethered-Token System Client ID**, then you'll need a[ ](https://dev.patientsknowbest.com/home/oauth2/system-client)<u>[Team Coordinator to grant you access from the web interface](https://wiki.hub.patientsknowbest.com/wiki/spaces/api/pages/3365404680)</u>.

# 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[ ](http://www.google.com/url?q=http%3A%2F%2Fdev.patientsknowbest.com%2Fhome%2Ffhir-api%2Ffhir-api-resources%2Fpatient%2Fexamples&sa=D&sntz=1&usg=AOvVaw11J_dSjTplbmlKSWTv5Rnz)<u>[example call taken from our FHIR documentation](https://wiki.hub.patientsknowbest.com/wiki/spaces/api/pages/3364028514)</u>, which shows how to use[ ](https://www.google.com/url?q=https%3A%2F%2Fcurl.haxx.se%2F&sa=D&sntz=1&usg=AOvVaw1m7OQHUPJ2SWZjCNiiBLn3)<u>[curl](https://www.google.com/url?q=https%3A%2F%2Fcurl.haxx.se%2F&sa=D&sntz=1&usg=AOvVaw1m7OQHUPJ2SWZjCNiiBLn3)</u> 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.

|  |  |  |  |  |
| --- | --- | --- | --- | --- |
|  | **Access token lifetime** | **Detecting expired access token** | **Session lifetime** | **Detecting expired session** |
|  |  | **Custom REST API** | **FHIR API**<br>**(Facade & Messaging)** | **FHIR API**<br>**(Customer & Aggregated)** |  | **Custom REST API** | **FHIR API**<br>**(Facade & Messaging)** | **FHIR API**<br>**(Customer & Aggregated)** |
| **User Client** | 10 minutes | The "errorMessage" string in the returned JSON begins with "access token has expired;" | [Error code](http://fhir.patientsknowbest.com/codesystem/response-code) :   
ACC_TOKEN_EXPIRED | Pending | Configured for your integration | HTTP 401 | [Error code](http://fhir.patientsknowbest.com/codesystem/response-code) :   
API_SESSION_EXPIRED | Pending |
| **Tethered-Token System Client** | 10 minutes | The "errorMessage" string in the returned JSON begins with "access token has expired;" | [Error code](http://fhir.patientsknowbest.com/codesystem/response-code) :   
ACC_TOKEN_EXPIRED | N/A; Tethered-Token System Clients cannot call the Customer & Aggregated FHIR endpoints | Configured for your integration | HTTP 401 | [Error code](http://fhir.patientsknowbest.com/codesystem/response-code) :   
API_SESSION_EXPIRED | N/A; Tethered-Token System Clients cannot call the Customer & Aggregated FHIR endpoints |
| **System Client** | 1 hour | N/A; System Clients cannot call the Custom REST API | HTTP 401 | N/A; System Clients cannot call the Customer & Aggregated FHIR endpoints | N/A; refresh tokens are not issued to System Clients |
| **Customer System Client** | 5 minutes | N/A; Customer System Clients cannot call the Custom REST API | N/A; Customer System Clients cannot call the Facade & Messaging FHIR endpoints | HTTP 401 is returned, along with this content:<br>{"message": "JWT is expired"} | N/A; refresh tokens are not issued to Customer System Clients |

## 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 <u>[chosen to grant access](https://www.google.com/url?q=https%3A%2F%2Fmanual.patientsknowbest.com%2Forganisation-administrator%2Fconnected-systems%23h.p_iNmFv650_ScZ&sa=D&sntz=1&usg=AOvVaw0bmxRBLasszcWG7vC1iSE-)</u>.

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[ ](http://www.google.com/url?q=http%3A%2F%2Fdev.patientsknowbest.com%2Fhome%2Ffhir-api%2Foperation%2Fread-receipt-query&sa=D&sntz=1&usg=AOvVaw0v8AXhkA3nH4_flfFR72I4)<u>[example call taken from our FHIR documentation](https://wiki.hub.patientsknowbest.com/wiki/spaces/api/pages/3364028514)</u>, which shows how to use <u>[curl](https://www.google.com/url?q=https%3A%2F%2Fcurl.haxx.se%2F&sa=D&sntz=1&usg=AOvVaw1m7OQHUPJ2SWZjCNiiBLn3)</u> 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**\" } ] }"