Patient grant access
- Sara Muse
Why
This one off process is done in order to ensure the user of the application is linked to their record in PKB and avoid the need for them to grant the application access to their PKB record every time they want to use it.
This process allows the app to determine the patient’s demographics, including identifiers stored within PKB, enabling further interaction with PKB’s APIs for that patient. See Patient demographic retrieval for further information.
Prerequisites
The patient already has a PKB record they can access.
If the patient doesn’t have access to a PKB record, the app will need to guide them on how to create one.
How to
Account Creation
Patient creates an account on the partner app.
The app ensures the patient login is associated with a unique app_user_id.
Initiating OAuth 2.0 Grant Access
From an appropriate screen in the app, the patient is given a link to the PKB “grant access” OAuth2.0 screens.
Authorization Code Grant Workflow
Patient grants access using OAuth 2.0.
Using the patient scoped User Client id, the patient grants access using the Authorization Code Grant workflow.
The url to provide is generated as described in this page of the PKB development wiki, using the user client id and the scope of PATIENT.
Authorization Code Retrieval
Following a successful login, PKB will return an authorization code to the app via the redirect URL provided by the app.
Token Exchange & Token Management
The app exchanges the authorization code for an access and refresh token which enable interaction with the PKB APIs specifically for that patient.
Using the authorization code as a parameter, you’ll swap it for an access / refresh token pair.
Further details with parameters and example call and response are here.
The patient will only do this authorization one time.
The app will need to maintain, manage, and associate tokens with the corresponding patient record in the app.