OAuth 2.0 · launch context · scopes
Charles Trinh — SMART App Launch | Las Vegas, NV · Las Vegas, Nevada · Henderson · Clark County, Nevada · North Las Vegas, Nevada

The authorisation layer that makes third-party apps viable
SMART on FHIR is well specified, widely implemented, and routinely built at half strength. The half that gets skipped is almost always enforcement, and enforcement is the part that matters when a real application with a real redirect URI and a real refresh cycle hits a production server.
It is also the half that determines whether an app ecosystem exists at all. An authorisation server that is strict, documented and predictable gets apps built against it. One that is vague gets a handful of bespoke integrations and a support queue.
Two launch contexts, two trust models
EHR launch supplies context — patient, encounter, sometimes the user — and the application inherits it. The server already knows who and what, so the scope request is checked against a known state rather than negotiated.
Standalone launch requires the application to establish context itself, usually by asking the user to select a patient. This is where enforcement gets loose, because the server shifts from trusting a launch token to trusting a parameter supplied by the client.
Both must work. Most deployments implement EHR launch thoroughly, because that is the demonstration scenario, and standalone partially, because that is the one real patients use.
Scopes are the contract
Patient-level and user-level scopes, read and write, plus launch and openid fhirUser for context and identity. Grant narrowly, and make the grant visible to the person authorising it.
The fhirUser claim is the one most often dropped, and it is the one that connects the token to a person the clinical record recognises, as a reference to a Practitioner or RelatedPerson. Without it your audit trail records an application, not a human, and "who looked at this record" becomes unanswerable.
Enforcement belongs in the data path
An application granted patient/Observation.read for one patient must not be able to read another patient's observations by changing a parameter. If the check lives in the route handler and the fetch lives in a shared service, the check is decoration.
Every read path must receive the granted scope and the launch context, not just the patient identifier from the request. Write scopes deserve separate scrutiny: a write granted for convenience will eventually be used for something the granter did not imagine, and the audit trail will show the application rather than the human behind it.
Revocation belongs to the member
Present the grant clearly, record it, honour revocation immediately. Deferring revocation to the next token refresh is a finding waiting for a complainant, and the fix is a grant-version check on the resource path rather than a shorter token lifetime.
Publish the configuration, then honour it
An accurate CapabilityStatement and /.well-known/smart-configuration are what clients build against without asking you. Advertising a scope you do not enforce is a promise you will be held to, and the failure mode is not a 403 — it is data returned to an application that should never have had it.
Publish the error semantics too. An app that receives a 400 with no body has no behaviour available to it and will file a support ticket, which is a cost you pay for a documentation defect.
Token discipline is ordinary OAuth, done properly
Short-lived access tokens. Refresh rotation with reuse detection. Audience restriction so a token issued for one resource server fails at another. PKCE for public clients. A token endpoint on a different origin from the application surface. None of this is exotic; healthcare implementations are weak on it precisely because the interesting problems are elsewhere.
Test with a real client
Run an open-source SMART client against your server rather than a curl script. The failures that matter appear only when a real application with a real redirect URI, a real scope request, and a real refresh cycle arrives. You find them by being one.
Then test the unhappy paths deliberately: modify a redirect URI, request a scope you have not registered, replay a refresh token, revoke mid-session. Four tests, one hour, and they cover the failures that actually occur.
What I do
I have built and run the SMART authorisation server for a platform that passed the ONC (g)(10) suite at 317 of 317, with the app-launch scenarios exercised as part of that run. I fix the enforcement layer first, because an authorisation server that grants correctly and enforces nothing is the most common state I find.
The app ecosystem is the point
A patient access API only creates value if applications exist to consume it. That is not a technical outcome; it is an economics outcome, and it depends on whether a developer can register, authenticate, and read data without a phone call to your organisation.
Publish a sandbox with synthetic patients and working credentials. Document the scopes you actually enforce, with examples of requests and the exact error responses for each failure. Keep the registration turnaround measured in days. An organisation that requires a business associate agreement and a security review before a developer can see whether the API works will have almost no applications, and will report that as a market problem rather than a friction problem.
Consent screens that a member can evaluate
The authorisation screen is the only place a member decides what an application may see. Most are written to satisfy legal review rather than to inform: a paragraph of policy language, a button, and no indication of scope.
Name the scopes in plain language — what the application will be able to read, for how long, and whether it can write. Name the application and its publisher. Make the refusal path as easy as the accept path. Record the decision with the scopes granted so that a later dispute is answerable from the record rather than from memory.
Standalone launch deserves its own tests
EHR launch is what gets demonstrated. Standalone is what real members use. The difference in trust model — the server accepting a patient context from the client rather than from a launch token — is where the enforcement weakness lives.
Test it adversarially. Authenticate for one patient, then change the patient parameter on a read request and confirm rejection. Request a scope that was not registered and confirm rejection rather than silent narrowing. Attempt a refresh with a token from a different grant and confirm the family dies. Those three tests take an afternoon and cover the failures that actually appear in production.
Error semantics are documentation
An application that receives a 400 with no body has no behaviour available to it, so it files a support ticket, which is a cost you pay for a documentation defect. Define the error shapes: invalid_scope, invalid_grant, invalid_token, insufficient scope versus unknown patient. Publish them with examples. Developers build against what they can read.
Write access is a different risk class
Read scopes leak data; write scopes corrupt it. A write granted for convenience will eventually be used for something the granter did not imagine, and the audit trail will record the application rather than the human behind it. Require an explicit, separately registered write scope, log the human via fhirUser, and treat write access as a privilege that expires.
What I do
I have built and run the SMART authorisation server for a platform that passed the (g)(10) suite at 317 of 317, with the app-launch scenarios exercised as part of that run. I fix the enforcement layer first, because an authorisation server that grants correctly and enforces nothing is the most common state I find.
Proof
- ONC (g)(10) self-test PASS, 317 of 317 subtests, April 2026 — public suite URL
- 67 public hostnames, 51 serving, one AWS account
- 104 clearinghouse enrolments across 53 jurisdictions
- USCDI v7 proposal — Patient Digital Identity Credential — listed at isp.healthit.gov
- SAM.gov UEI MVKQW9DKKGB8 · CAGE 20KM5 · NPI 1194645564
- AWS Business Associate Addendum active since 18 August 2026
Where this work is delivered
Engagements run from Las Vegas and reach across the valley: clients in Las Vegas, NV; Las Vegas, Nevada; Henderson; Clark County, Nevada; and North Las Vegas, Nevada — plus remote delivery nationwide.
Engagement
Scoped in writing before work starts; fixed fee where the deliverable is defined. First call is 20 minutes and free. 702-559-3489 · charles@trinh.io
Talk to Charles
- Phone: 702-559-3489
- Email: charles@trinh.io
- Based in Las Vegas, Nevada · working remotely across the United States
How an engagement runs
1. Trace one real case
Follow a single patient or claim end to end with a timestamp at every hop, before any document is written.
2. Written findings
A findings list naming the defect, the system, the owner and the date.
3. Monthly review
Review the list monthly and check whether the dates held.
Frequently asked
What is this service?
This page describes charles trinh — smart app launch — the scope, the failure modes it prevents and how the work is measured. It sits in the Interoperability category at trinh.io.
Where is the work delivered?
Engagements run from Las Vegas, Nevada across the valley — Las Vegas, Henderson, North Las Vegas, Spring Valley, Paradise, Winchester, Sunrise Manor, Enterprise, Summerlin, Clark County — and remotely anywhere in the United States. On-site work in the Las Vegas valley, remote delivery elsewhere.
What does it cost?
Standard rate $195 per hour, committed $165 per hour at twenty hours or more per week for three months or more; $1,600 standard day, $1,350 committed day. Scoped in writing before work starts, fixed fee where the deliverable is defined.
Who is Charles Trinh?
A technology architect in Las Vegas, Nevada, working in healthcare identity, consent and interoperability. Not a physician, not a medical practice, and not affiliated with any other Charles Trinh.
How does an engagement start?
With one trace of a real case and a written findings list naming the defect, the system, the owner and the date. The first call is twenty minutes and free: 702-559-3489.
Record
Profile
Healthcare technology architect working where federal regulation becomes production infrastructure. Built and operates a FHIR R4 clinical platform — SMART App Launch authorization server, patient and provider portals, SQLite — on a hardened single-host AWS estate of 67 public hostnames. The platform returned a self-test PASS on the ONC (g)(10) Standardized API test suite in April 2026, 317 of 317 subtests, publicly verifiable. Designed a consent architecture in which a permissioned ledger records patient grant, refusal and revocation as immutable events while all clinical data stays off-chain and encrypted per patient — no PHI on the ledger by design. Filed a proposed USCDI v7 data element with ONC on verifiable patient identity. Translates the Federal Register, HHS/CMS guidance and HITRUST requirements into architecture, controls and audit evidence.
Selected engineering scale
- Self-managed estate of 67 public hostnames, 51 serving, on one AWS account.
- FHIR R4 API with a SMART App Launch authorization server; patient and provider portals; an AI service layer; Hyperledger Fabric peer, orderer and CA; IPFS; a 337-table SQLite clinical store.
- Two permissioned distributed ledgers in production, one operating a consent registry that records grant, refusal and revocation with no PHI on chain.
- X12 005010 pipelines across eight transaction sets.
- Designed, built, deployed and operated end to end by one person.
Credentials and standards work
- Inferno (g)(10) self-test PASS, 317 of 317 subtests, April 2026 — the ONC Standardized API test suite. Standards validated: US Core 6.1.0, USCDI v3, SMART App Launch 2.0.0, Bulk Data 2.0.0. Public suite URL.
- USCDI v7 public comment submission, April 2026 — proposed Patient Digital Identity Credential under the Provenance data class, listed publicly on the ONC Interoperability Standards Platform.
- SAM.gov UEI MVKQW9DKKGB8 · CAGE 20KM5 · NPI 1194645564. AWS Business Associate Addendum active 18 August 2026.
Technical environment
AWS us-east-1 (compute, storage, messaging, SMS, email, voice) · Linux and systemd hardening · nginx · Fabric and EVM ledgers · FHIR R4 · X12 005010 · HL7 · SQLite · self-hosted mail, drive, search and monitoring · Git-based change control and CI release gates.