Authorization
How a patient grants your app access to their records, and what Medblocks handles for you.
When a patient connects in your app, they are doing one specific thing. They are granting your app permission to read their records from their hospital. That permission step is the authorization, and it runs on a healthcare standard called SMART on FHIR.
You do not build any of this. You start a patient session, the patient approves at their hospital, and Medblocks runs the standard underneath. This page explains what is happening, so you can reason about it, handle the cases where it fails, and trust the access behind your data.
SMART on FHIR in one minute
SMART on FHIR is OAuth 2.0 shaped for healthcare, and OAuth is the same pattern as “Sign in with Google”. The patient signs in at their hospital, not in your app, and grants you limited, revocable access to their data. Two things follow from that, and both matter to you.
- Your app never sees the patient’s hospital password. They type it on their hospital’s own page.
- The hospital decides what you can read and can revoke it at any time. You ask, the patient approves, and the hospital grants access on its terms.
What the patient is approving
Your app asks for a set of permissions, called scopes. For patient access these cover reading the patient’s own clinical data, confirming who they are, and keeping access alive after they leave. You do not assemble them, Medblocks requests the right scopes for each source. The one worth knowing by name is offline_access, because it is what lets Medblocks keep pulling records after the patient closes the tab. Without it you would get a single snapshot and nothing after.
What Medblocks handles for you
Once the patient approves, Medblocks and the hospital run a short exchange to turn that approval into usable access. Medblocks builds the request, uses a technique called PKCE to keep the exchange safe so an intercepted approval cannot be reused, trades the approval for an access token, and stores that token on its own side. Your app never handles the token, and you never write token storage or refresh code.
None of this is yours to build. It is here so you know what “Medblocks runs the sign-in” actually means.
Keeping access alive
Access tokens are short lived by design, often under an hour. So along with the access token, offline_access gives Medblocks a longer-lived refresh token, and Medblocks uses it to renew access quietly in the background. Records keep flowing without asking the patient to sign in again.
Renewal can stop working, usually because the patient revoked access or too long passed. When it does, the connection moves to refresh_failed. That is the one case that comes back to you. When you see it, prompt the patient to connect again.
When something goes wrong
The patient signs in on a system you do not control, so a connection can fail in a few ordinary ways. Treat these as normal states in your UI, not errors to bury.
| What happened | What your app should do |
|---|---|
| The patient cancelled or declined at their hospital | Offer to try again |
| The hospital returned an error | Log the patient session ID, show a retry, read the session for the reason |
| The session link expired before they finished | Start a new patient session |
Access lapsed later (refresh_failed) | Prompt the patient to reconnect |
Debugging a connection
Every attempt a patient makes leaves a trail you can read in the dashboard. It shows which source they tried, whether they reached the hospital, whether consent went through, and a stable error code when it did not. When a patient tells you it did not work, that history is where you see why, and whether the problem was at the hospital or in how your app set up the session.