What is a scope?

There are 3 different types of user in PKB which can authenticate against the REST API:
  • Patient
  • Clinician
  • Team Coordinator
Each REST operation is restricted to one or more of these user types. The scope of each operation defines which user types are authorised to call it, and is specified in the documentation for each operation.

User Client IDs

Sessions authenticated using a User Client ID are restricted to the scope specified when the session was established. For example, if you specified scope=PATIENT when establishing the session, you will only be able to execute REST operations with a scope of PATIENT.

As an example, this operation can be used to deactivate a PKB account. The comment for this operation states "Scope: TEAMCOORD". This indicates that only someone currently authenticated as a TEAMCOORD can call this operation. If you try to perform this operation whilst authenticated as a patient, you will see an error message along the lines of "User type PATIENT can't execute API call requiring scope TEAMCOORD".

System Client IDs

In contrast, System Client IDs must always specify a scope of SITE when establishing a session. This is a special scope that is only available to System Client IDs, and will grant access to both CLINICIAN and TEAMCOORD scoped functionality.

Which user types will my Client ID let me authenticate as?

When you obtained your Client ID, we will have agreed with you which scopes you are authorised to use. If you'd like to check or change your configuration, please email us at

If you have a System Client ID, you must always specify a scope of SITE.

Consent implications

Only consented data is retrievable via Rest queries. If client scoped, the authorization for the user must have consent granted to view this data for the privacy labels tagged. The same holds true for site scoped requests, the organization must have the same matching level privacy tags to be able to retrieve data. 

Bypass Consent via API

Teams require the ability retrieve and update data for patients that have not consented or shared all privacy labels with them, this functionality is referred to as Break The Glass. Patients Know Best has enabled a BTG workflow in the REST API for clients that wish to connect via REST. More information here: Break The Glass via REST
Subpages (1): Break The Glass via REST