Build an athenahealth FHIR App

What does it take to build an athenahealth FHIR app?

Building an athenahealth FHIR app takes a registered SMART on FHIR client, an OAuth 2.0 flow that matches the app's users, practice-aware request handling, and US Core reads mapped into your product. athenaOne serves many practices from one cloud platform, so every call must resolve to the right practice and stay inside the scopes that practice approved.

The app is not a database connection or a nightly file. It is a client that asks athenaOne for specific records with a short-lived token, and it should behave correctly when a practice grants less access than the developer sandbox did.

Who will use the app: clinicians, patients or a system?

Decide the audience before writing code, because clinicians, patients and background jobs each get a different OAuth flow, different scopes and different legal terms. Ambulatory products often need two of the three.

• Clinician app: A provider or staff member opens the app with a practice's chart context. Typical uses are intake review, care gap lists, specialty calculators and documentation support.
• Patient app: The patient signs in from outside the EHR and authorizes the app to read their own record. Typical uses are personal health records, chronic condition tracking and research enrollment.
• System app: A server-side client runs with no user present, using SMART backend services. Typical uses are scheduled syncs, quality reporting and panel refreshes for a care team.

Register each audience as its own client. Mixing a patient flow and a staff flow in one client makes scope review harder for the practice and makes it impossible to revoke one without the other.

The audience also decides who your customer is. A clinician or system app is usually bought by the practice. A patient app is usually chosen by the patient, which changes the contract and privacy terms covered later in this article.

Practice context on a shared cloud EHR

On athenaOne, the practice is part of every request, because one hosted service holds records for many separate practices. Your app has to carry the correct practice identity from launch through every FHIR call and into your own database.

athenahealth's developer documentation sets out how the practice is identified on FHIR requests. Read that guidance for the API version you build against, implement it as configuration in one place, and never infer the practice from a patient ID alone.

• Store the practice with every record: Each patient, appointment or observation you persist carries the practice it came from, so data from two practices never merges by accident.
• Scope your caches: Cache keys include the practice, so a cached patient list from one practice is never served to another.
• Keep per-practice settings together: Enabled features, local identifiers and contacts for each practice live in one configuration record that support staff can read.
• Test with two practices early: A second test practice in the sandbox catches hard-coded identifiers before a real rollout does.

Practice-level settings also differ. Departments, provider lists and enabled features vary between practices, so treat each one as a configuration record rather than assuming the first practice is typical.

How do you build an athenahealth FHIR app step by step?

An athenahealth FHIR app is built in six steps, from registration in athenahealth's developer program to the first practice in production. The early steps happen in the sandbox; the later ones need a practice that has agreed to pilot the app.

• 1. Register: Create the app in athenahealth's Developer Portal, declare its audience, redirect URIs and requested scopes, and receive its client credentials.
• 2. Implement the SMART flow: Read the server's SMART configuration, request authorization with PKCE and a state value, exchange the code, and record the granted scopes and context.
• 3. Add practice context: Carry the practice identity through every request using the method athenahealth documents, and store it alongside every record.
• 4. Map US Core data: Read the resources the feature needs, map them into your product's model, and handle paging, missing elements and OperationOutcome errors.
• 5. Pilot: Run the app with one practice and one workflow. Compare what users see in your app with the chart in athenaOne for a sample of real patients.
• 6. Roll out: Add practices one at a time through configuration, watching sign-in failures, authorization errors and data mismatches per practice.

athenahealth also offers proprietary APIs alongside FHIR, and it runs a Marketplace program for partner apps. Whether a feature needs a proprietary API, and whether to join the Marketplace, are product decisions to settle before step 1.

Keep sandbox and production configuration fully separate, including client credentials and redirect URIs, and show the current environment on the app admin screen so support staff can tell which one a user is on.

Which data should the first release use?

The first release should read a small set of US Core resources that one workflow truly needs, such as Patient, Encounter, Condition, Observation and MedicationRequest. A narrow first release is quicker to review and easier for a practice to trust.

Ask for read and search access only, unless a write is the core of the product. SMART version 2 scopes make this explicit: a scope such as patient/Observation.rs grants read and search on Observation and nothing else.

• ASTP/ONC's (g)(10) criterion at 45 CFR 170.315(g)(10) is limited to read services for single and multiple patients and leaves out write capabilities, so a certified EHR is not required to accept writes through it.
• ASTP/ONC names US Core 6.1.0 and SMART App Launch Release 2.0.0 as standards for (g)(10), which sets the profiles and scope syntax a certified FHIR server supports.
• The HL7 SMART App Launch guide defines scope permissions as create, read, update, delete and search, written as letters after the resource type.
• The HL7 SMART backend services profile has the client authenticate with a JSON Web Token signed by its own private key instead of a shared secret.

Plan writes as a second release with the practice's clinical lead. Any write to the record needs a named owner who confirms where the data lands and who reviews it.

Does an athenahealth FHIR app need a BAA?

It depends on who the app works for. An app that a practice uses to handle patient data on the practice's behalf is a business associate and needs a business associate agreement with the practice; an app the patient chooses to receive their own records is not the practice's business associate.

• Clinician and system apps: The developer performs a service for the practice, which makes it a business associate under 45 CFR 160.103, and the contract must meet 45 CFR 164.504(e).
• Patient-directed apps: When a patient uses their right of access to send records to an app they picked, HIPAA does not make that app the practice's business associate. Such an app may instead have breach duties under the FTC rule at 16 CFR Part 318.
• Synthetic sandbox data: The sandbox does not change the answer. Sign the agreement before the first real patient record reaches your system.

Write the decision into the product plan, because it also decides your privacy notice, breach process and the security questions the practice will ask.

Readiness list for the first practice

Work through this list before the first practice goes live. It covers the questions a practice and its IT adviser can be expected to raise before agreeing to a pilot.

• Audience and clients: One registered client per audience, each with the smallest scope set that works.
• Practice context: Practice identity carried on every request, stored on every record and included in every cache key.
• Second practice test: The app has run against at least two sandbox or pilot practices without code changes.
• Token handling: Tokens are kept out of logs and browser storage, refreshed before expiry, and revoked on sign-out.
• Error behavior: Every feature handles an authorization error, an empty result and an OperationOutcome with a clear message.
• Contracts: The business associate decision is documented, and the agreement is signed where one is needed.
• Accessibility: Practices that receive HHS funding must meet WCAG 2.1 Level AA for their web content and mobile apps under 45 CFR 84.84, and larger recipients (15 or more employees) must comply by 11 May 2027, so build patient screens to at least that level.
• Monitoring: Sign-in failures, authorization errors and data mismatches are tracked per practice with a named owner.

How Agnotic can help

An athenahealth app succeeds when the tenth practice is as easy to add as the second. Agnotic Technologies builds SMART on FHIR apps for athenahealth practices around that goal: separate clients per audience, practice context carried end to end, US Core mapping, token handling and per-practice monitoring.

Agnotic also helps product teams decide between FHIR and athenahealth's proprietary APIs for each feature, and plans the business associate and accessibility work alongside the code.

Sources

• HL7: SMART App Launch, scopes and launch context
• HL7: SMART App Launch, backend services
• HL7: US Core implementation guide
• ASTP/ONC: Standardized API, 45 CFR 170.315(g)(10)
• 45 CFR 164.504(e): Business associate contracts
• 45 CFR 164.502(e): Disclosures to business associates
• Federal Register, 11 May 2026: Extension of Section 504 web and mobile accessibility compliance dates