LlamaIndex Agents Calling FHIR APIs: SMART on FHIR Scopes vs Runtime Enforcement
SMART on FHIR scopes authorize an application at token issuance: which FHIR interactions on which resource types the token may use. They do not evaluate each call a LlamaIndex agent chooses to make, whether it fits the task, or what PHI comes back into model context. Treat scopes as the baseline at the authorization server, and enforce per-call decisions (allow, redact, block, rate limit, escalate) in the agent's execution path.
Where enforcement sits in the tool-call path
- 1
Pre-call decision
Evaluate tool, resource, parameters, identity and task. Outcomes: allow, block, rate limit, escalate.
- 2
Post-response decision
Evaluate returned content before it enters model context. Outcomes: allow, redact, block.
- 3
Grant validity check
Confirm the token is still valid, using introspection where the server supports it.
Decisions to make before an agent touches a FHIR server
- Which identity does the agent run under, patient, user or system, and how narrow are the CRUDS permissions per resource type?
- Does the target FHIR server support SMART v2, PKCE and Token Introspection, and how quickly does it act on revocation?
- Can a policy decision be made before the FHIR request and again before the response reaches the model?
- Which fields must be redacted before model context, and which calls require human approval?
- What volume or pattern of queries triggers a rate limit or escalation?
- What per-call evidence is retained, and how does it link back to the token grant?
What SMART on FHIR scopes control
SMART App Launch is a profile of OAuth 2.0, paired in CMS and ONC rules with FHIR R4.0.1 and OpenID Connect Core 1.0. Version 2 adds support for PKCE and a revised scope syntax. Its scopes are built from combinations of five permission types that match the FHIR Create, Read, Update, Delete and Search interactions. Version 1 offered only read and write, so v2 allows narrower grants. As of November 2026, SMART App Launch IG 2.0.0 is the version adopted at 45 CFR 170.215, and under the HTI-1 final rule it is the only version available in the ONC certification program from January 1, 2026.
Authorization happens when an application is granted access and a token is issued. For system scopes, that means SMART Backend Services. The authorization server must also be able to revoke an application's access at a patient's direction within one hour of the request, and Token Introspection is a mandatory capability in the adopted guide. These rules apply to certified health IT and its APIs. They do not directly regulate a client you build yourself, so treat them as the baseline your agent inherits, not as a compliance statement about the agent.
Where an agent-driven client outgrows scopes
In a LlamaIndex agent, a tool is typically a wrapped function, for example a FunctionTool around code that issues a FHIR request. The model decides which tool to invoke and what arguments to pass. The function then runs with whatever token the process holds. From the FHIR server's perspective each call is an ordinary RESTful interaction. It checks the request against the token's scopes and nothing more.
That is the gap. A token scoped to read Observation resources permits any Observation read or search, whether the task needs one lab value or an entire patient panel. The scope cannot express the stated task, because the task lives in the prompt and the model's reasoning. It cannot tell a targeted lookup from a loop that pages through results. It also has no view of the response: once the server returns PHI, nothing in the grant decides whether that content should enter model context in full, in part, or not at all.
The identity path matters too. An agent acting under a user-facing launch carries patient or user scopes tied to a person. An agent using backend services carries system scopes tied to an application. The second case is broader by design, which makes per-call controls more important, not less.
Mapping agent failure modes to the layer that addresses them
Each failure mode below is best handled at one layer, with the other layer as a backstop. The mapping is architectural reasoning, not a statement of what any specification requires.
- Over-broad scope grant: Authorization server: request the narrowest CRUDS combinations per resource type. Runtime: block interactions the task never needs, even if the token allows them.
- Tool selection driven by model output: Authorization server: cannot see tool choice. Runtime: evaluate each tool call and its parameters against policy before the FHIR request is sent.
- Out-of-task queries: Authorization server: cannot judge task fit. Runtime: allow, block or escalate for human approval based on the stated task and the requested resource.
- PHI returned into model context: Authorization server: grants read access only. Runtime: redact fields in the response before it reaches the model.
- Repeated or bulk queries: Authorization server: no per-request volume control in the grant. Runtime: rate limit, or escalate when volume exceeds what the task justifies.
- Access that should have ended: Authorization server: revocation and token validation. Runtime: stop tool calls when the grant is no longer valid.
Evidence each layer produces
An auditor or regulator will want to know what the agent was allowed to do and what it did. Those are different questions, answered by different records.
The authorization layer answers the first. It can show which application was registered, which scopes were granted, when the token was issued, and when access was revoked. This is token-level evidence. It shows the ceiling of what was possible.
It cannot show what happened under that ceiling. A single token may back thousands of agent calls, and the issuance record says nothing about which resources were requested, with what parameters, for which task, or what was redacted before the model saw it. That requires per-call evidence from the runtime layer: the tool called, the resource and parameters, the policy decision, any redaction applied, and any approval and who gave it.
The two sets should be correlatable, so a reviewer can move from a grant to the calls made under it. Trussed generates audit-ready evidence from enforcement itself, mapped to HIPAA, so the record is a product of the decision rather than a reconstruction afterward. Your own retention and residency requirements should drive where that evidence lives, and Trussed supports self-managed deployment in the customer cloud with configurable retention and data residency.
Two layers between an agent and a FHIR server
Authorization server
Issues a token with scopes. Limits what the token can ever do. Handles revocation.
Tool-call enforcement
Evaluates each request and response in the execution path before the FHIR call and before data reaches the model.
Evidence
Token-issuance records show what was granted. Per-call records show what the agent actually did.
Review your agent's FHIR access path
See how policy enforcement in the execution path applies allow, redact, block, rate limit and escalation to individual tool calls, and how it produces audit-ready evidence.
Request a Demo