Scopes

Owned by Andrew Turner (Unlicensed)
Last updated: Jul 04, 2022 by Mohammad Al-Ubaydli
2 min read

What is a scope?

There are 3 different types of user in PKB which can authenticate using the OAuth 2.0 flow:

  • 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.

PKB supports 3 different types of client IDs, and these have different scopes available to them.

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".

Tethered-Token System Client IDs

In contrast, Tethered-Token System Client IDs must always specify a scope of SITE when establishing a session.

This is a special scope that is only available to Tethered-Token System Client IDs, and will grant access to both CLINICIAN and TEAMCOORD scoped functionality.

System Client IDs

System Clients are not permitted to call the Custom REST API.

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 integrations@patientsknowbest.com. If you have a System Client ID, you must always specify a scope of SITE.

Consent implications

Only data for which you have consent will be returned from REST API queries. This is true regardless of which scopes you are using. If you are using a User Client ID, then the authenticated user must have been granted access to the corresponding privacy label to view the data. If you are using a System Client ID, then the associated team must have been granted access to the corresponding privacy label to view the data.

Bypassing consent in the API

In some circumstances, such as a medical emergency, teams require the ability retrieve data for which they have not been granted the corresponding privacy label. This functionality is referred to as Break The Glass. Please see here for more information on how to use this workflow in the REST API.