Building an Athenahealth SMART on FHIR Embedded App with Node.js

Modern healthcare workflows demand applications that are embedded, context-aware, and secure. Providers should not switch systems or re-authenticate to access critical tools.

SMART on FHIR enables third-party applications to launch directly inside Electronic Health Records (EHRs) with full patient and provider context.

This document provides a complete, end-to-end guide for building a SMART on FHIR embedded application for Athenahealth using Node.js, designed for service-to-provider-to-service workflows.

What is Athenahealth?

Athenahealth is a leading cloud-based Electronic Health Record (EHR) platform widely used by healthcare providers across the United States.

Athenahealth provides:

• Clinical documentation
• Scheduling and billing
• Revenue cycle management
• Patient engagement tools
• Developer APIs for interoperability

Athena supports SMART on FHIR, allowing third-party applications to embed directly inside the provider’s EHR interface, enabling seamless clinical workflows without additional logins.

What is SMART on FHIR?

SMART on FHIR (Substitutable Medical Applications & Reusable Technologies) is an industry standard that defines how applications securely integrate with EHR systems.

SMART on FHIR combines:

• FHIR for healthcare data exchange
• OAuth 2.0 for authorization
• OpenID Connect for user identity

Key capabilities:

• Single sign-on (SSO) for providers
• Automatic patient and encounter context
• Standardized permission scopes
• Vendor-agnostic app architecture

SMART allows the same app to work across multiple EHRs with minimal changes.

SMART Embedded App Concept (Athena)

A SMART embedded app:

• Launches from inside Athena’s EHR UI
• Requires no separate login
• Receives patient, provider, and encounter context automatically
• Uses OAuth tokens to securely access FHIR APIs

Example Provider Workflow:

1. Provider opens a patient chart in Athena
2. Provider clicks the embedded app
3. Athena launches the app with context
4. App fetches FHIR data and renders insights

Prerequisites

Before starting, ensure you have:

• Athenahealth Developer Portal access
• Athena Sandbox EHR access
• Sandbox provider user accounts
• Node.js (18+ recommended)
• Understanding of:
  → OAuth 2.0
  → OpenID Connect
  → SMART on FHIR
  → FHIR R4 resources
• A public HTTPS endpoint (e.g., ngrok for development)

Step 1: Pre-Planning & Scope Definition

Define Your Use Case

Clarify:

• Provider roles using the app
• Where the app launches (patient chart, workflow tab, etc.)
• Read-only vs read/write data access
• Need for background processing or long sessions

Common SMART Scopes

Typical provider-facing scopes include:

launch

patient/*.read

openid

profile

fhirUser

offline_access (optional)

Always request the minimum required scopes.

Step 2: Register Your App in Athena Developer Portal

1. Log in to Athenahealth Developer Portal
2. Create a new SMART on FHIR Application
3. Configure:
   • App Name & Description
   • App Type: Confidential
   • Launch URL
     https://yourapp.dev/launch
   • Redirect URI
     https://yourapp.dev/callback
   • Required scopes
   • OpenID support enabled
4. Save and record:
   • client_id
   • client_secret

Redirect URIs must match exactly.

Step 3: Coordinate with Athena (Critical Step)

Create a support ticket with Athena requesting:

• SMART app whitelisting
• Athena Sandbox EHR access
• Provider test accounts
• Embedded app configuration in sandbox UI
• Confirmation of:
  → OAuth authorization endpoint
  → Token endpoint
  → FHIR base URL
• API rate limits and usage policies

This step enables your app icon to appear inside the Athena EHR.

Related read: Integrating FHIR Resources with Backend Services: A Comprehensive Guide

Step 4: Athena Sandbox EHR Setup & Testing

Once approved:

1. Log in to Athena Sandbox EHR as a provider
2. Open a patient chart
3. Launch your embedded app
4. Confirm Athena passes:
   → iss (FHIR server URL)
   → launch token
5. Verify successful OAuth redirect and token exchange

Step 5: Node.js Application Setup

Initialize Project

mkdir athena-smart-app

cd athena-smart-app

npm init -y

npm install express fhirclient dotenv

Environment Variables

CLIENT_ID=your_client_id

CLIENT_SECRET=your_client_secret

REDIRECT_URI=https://yourapp.dev/callback

SCOPES=launch patient/*.read openid profile fhirUser offline_access

Step 6: Implement SMART Launch & OAuth Flow

Launch Endpoint

• Receives iss and launch from Athena
• Initiates SMART authorization

OAuth Callback

• Exchanges authorization code for tokens
• Accesses FHIR APIs using the issued access token
• Fetches patient or provider data securely

This logic runs entirely on the backend.

Step 7: Testing the Embedded App

Validate:

• App launches from Athena UI
• OAuth flow completes successfully
• Patient context is available
• FHIR resources return expected data
• Errors are handled gracefully

Any launch issues can be debugged with Athena support.

Step 8: Token Management & Long Sessions

If offline_access is enabled:

• Store refresh tokens securely (encrypted storage)
• Automatically refresh access tokens
• Never expose tokens to the browser

This supports:

• Long provider sessions
• Background jobs
• Async processing

Step 9: Security & Compliance Best Practices

• Enforce HTTPS everywhere
• Validate iss issuer URLs
• Store secrets securely
• Do not log PHI
• Limit scopes to a minimum
• Follow HIPAA and Athena security guidelines

Step 10: Production Deployment & Go-Live

Before production:

• Update production URLs in Athena Developer Portal
• Complete Athena production approval
• Perform UAT with real provider users
• Monitor:
  → Token failures
  → API rate limits
  → Error logs