Developer documentation‎ > ‎REST API‎ > ‎Scopes‎ > ‎

Break The Glass via REST

Purpose

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.

Approach

REST API exposed allowing users to invoke a POST passing in userID (audit purposes) and pkbId (patient to retrieve data on) enabling BTG access for patient data for 30 minutes.

Workflow

  1. BTG API called passing patient id (pkbId) and user making call (for audit purposes)

  2. On successful invocation a BTG authorization token is returned with a Time To Live (TTL) of 30 minutes associated with subsequent API calls for that patient

  3. Subsequent API’s called retrieving data utilizing BTG authorization token

         Calls will require another parameter (breaktheglass) to be passed in the message header like below:

Audit

PKB will track which team (associated by authorization token) and user (associated by BTG request parameter) has viewed and updated patient data via BTG API. Cases where teams utilized shared user accounts will require their own auditing process to track user access.

Request

POST /v2/consents/BTG/{patientId}

Parameters

  • pkbId (patient to BTG on)

  • https://sandbox.patientsknowbest.com/api/index.html#!/Break_The_Glass/getBtgToken


Response

  • 200 Success - Consent levels set to BTG against patient (pkbId) for requestor (userId) valid until dd:HH:mm:ss

  • 401 Unauthorized - Login context is null. Error opening authorization request with supplied tokenHeader. Method requires a user within scope(s) CLINICIAN and BTG functionality enabled  but current user is of UserType PATIENT

  • 404 Not Found - Patient not found

Audit of BTG usage

  • PKB maintains an audit trail of accesses via BTG.

  • For the REST access, PKB will track the user (userId) making the request as well as any data accessed under BTG.

  • Notification about BTG access having occurred will be visible to the patient and their teams via the PKB GUI

  • It may not always be possible for clients to have a 1:1 mapping between users of the REST BTG and userId. It will be the responsibility of the client organisation to provide the internal governance to allow more granular, actual user-level, auditing of use.

Sample BTG API Workflow

Comments