v0.1 · Working foundation

Ignite your app.
Simplify the SMART.

SMART Flint is a self-hosted SMART on FHIR integration service. It manages the connection lifecycle between your application and an organization’s FHIR environment.

Download & install View source ↗

Source available · Community licensing for eligible use · No hosted account required

CHOOSE HOW MUCH TO DELEGATE

Keep credentials at the bridge

Your applicationSMART FlintFHIR server

Your app reads and searches through SMART Flint. The bridge holds upstream credentials, manages renewal, and applies its gateway policies.

const connection = await session.getFHIRConnection({
  route: 'gateway'
});

Ordinary FHIR HTTP clients work. Gateway access uses a SMART Flint session credential.

Keep your existing FHIR client

Your applicationOriginal FHIR server

Your app talks to the original FHIR endpoint with its upstream access token. SMART Flint continues to own credential renewal.

const connection = await session.getFHIRConnection({
  route: 'direct'
});

Token export must be allowed by the installation. Gateway-specific controls apply only to gateway traffic.

Take ownership explicitly

Your applicationOriginal FHIR server

Your app explicitly takes ownership of the upstream credentials. The bridge stops owning refresh-token rotation for that grant.

POST /api/activations/:id/credentials/handoff

Independent refresh may also require confidential client authentication on your backend. Handoff is a separate API action.

Understand credentials & ownership

Illustrated architecture · not a live EHR connection

Self-hostedYour infrastructure and operating model

SDK optionalStandard HTTP and your preferred FHIR client

Multiple access pathsGateway, direct, or credential handoff

Source availableInspect, modify, and use under clear terms

What it does

The connection work.
In one place.

Applications need more than a FHIR URL. SMART Flint brings launch, authorization, tenant configuration, and context delivery into a coherent service.

Launch orchestration

Support EHR-initiated and standalone launches with upstream and downstream S256 PKCE, exact callbacks, browser binding, and single-use activation codes.

Read the guide ↗

Application-first configuration

Manage EHR platforms, organization-owned FHIR connections, vendor app registrations, client profiles, installations, and policies in one linked workspace.

Read the guide ↗

Context & credential lifecycle

Deliver launch context, hold encrypted upstream credentials, renew access, and explicitly transfer refresh ownership when the application needs it.

Read the guide ↗

FHIR read/search gateway

Read resources, version reads, metadata, and JSON searches through an activation-scoped gateway. Use controlled pagination and optional display-whitespace normalization.

Read the guide ↗

SMART Backend Services

Acquire application-specific backend access with asymmetric JWT client authentication. Use the optional Python SDK for service integrations.

Read the guide ↗

CDS Hooks forwarding

Forward authenticated synchronous hook requests with request-bound prefetch and context, signed caller JWT verification, and replay protection.

Read the guide ↗

Administrative control

Choose local password accounts or one OIDC provider. Assign scoped integration and viewer roles, inspect redacted records, and trace actor-attributed audit events.

Read the guide ↗

Self-hosted operations

Run a containerized service with PostgreSQL, configure HTTPS, retain encrypted records under bounded policies, and follow backup, restore, and key-rotation runbooks.

Read the guide ↗

SDKs, samples & a developer lab

Use TypeScript and Python SDKs, native integration examples, a synthetic EHR, and Health Compass reference apps to learn the connection lifecycle.

Read the guide ↗

Where it fits

Your application.
Less integration plumbing.

Use SMART Flint as the connection layer beside your application. Keep business logic and your preferred FHIR client in your own code.

Web applications: start a launch, complete a callback, receive context, and obtain the selected FHIR connection.
Multi-organization products: resolve the organization and connection at runtime instead of hardcoding tenant URLs.
Backend integrations: acquire authorized service access without a user-facing launch.
Clinical decision support: connect authenticated CDS Hooks callers to your configured synchronous handler.

The integration model

1
Application
Callback URLs, context, scopes, and permitted access modes.
2
EHR platform & registration
Vendor registration and environment-specific client profile.
3
Organization & FHIR connection
The actual organization endpoint and approved discovery settings.
4
Installation
Bind the app, registration, and connection to an access policy.
5
Activation
A bounded runtime session carrying launch context and access.

Understand the workspace

Real EHR connections need real onboarding.

The included vendor-labeled environments are synthetic protocol simulators. They do not demonstrate vendor compatibility or certification. Registration and organization-specific verification remain necessary.

Choose your boundary

One lifecycle.
Three access models.

SDK use and gateway use are independently optional. Choose a mode per installation, subject to its policies and supported upstream grant.

Mode	Clinical request path	Who owns renewal?	Useful when
Gateway	Application → SMART Flint → EHR	SMART Flint	You want upstream credentials held at the bridge and mediated read/search access.
Direct	Application → EHR	SMART Flint	You want the original endpoint and token with bridge-managed renewal.
Handoff	Application → EHR	Your application, after explicit handoff	Your backend must take over credential lifecycle management.

Direct token export is an installation policy. Gateway tokens and upstream access tokens are different credentials. Handoff does not export confidential client secrets or private keys. Sender-constrained grants are rejected in this version.

Read the access & credential guide

Developer experience

A launch. A callback.
Your FHIR client.

The optional TypeScript SDK handles the launch transaction and activation session. Install its package from a local build or an available release artifact.

1 / Start a standalone launch

import { SMARTFlintClient } from '@smart-flint/sdk';

const flint = new SMARTFlintClient({
  baseUrl: 'https://flint.example.com'
});

const launch = await flint.start({
  installationId: 'your-installation-id',
  redirectUri: 'https://your-app.example.com/callback',
  mode: 'direct'
});

window.location.assign(launch.launchUrl);

2 / Complete the registered callback

const { activation, sessionToken } =
  await flint.completeRedirect();

const session = flint.session(
  activation.id, sessionToken
);
const connection = await session.getFHIRConnection({
  route: 'direct'
});

// Use your FHIR client with connection.baseUrl and
// connection.credentials.getAuthorizationHeader().

Configure an installation and exact callback URL first. Keep the activation session in memory or on your backend. The browser SDK stores short-lived PKCE transaction material in session storage. Public npm publication is a separate release step; see SDK installation and integration.

A complete learning environment

Try the lifecycle.
See the moving parts.

Start a local sandbox without vendor accounts or production credentials. The Developer lab lets you compare access modes, change synthetic patients, and explore ownership transfer.

Console and reference application, synthetic EHR, and interactive launch tooling.
Health Compass patient-facing sample, CDS Hooks handler, and headless FHIR assessment service.
Four synthetic patient scenarios with an explainable educational assessment model.

Explore the sample library

macOS / Linux · Docker guided setup

git clone https://github.com/davidvaccaro/smart-flint.git
cd smart-flint
bash ./install.sh

Prefer source development?

Use the supported Node.js version pinned in the source checkout, then run npm install and npm run dev. Windows users can use ./install.ps1 for guided Docker setup.

All installation paths & prerequisites ↗

The Health Compass model is educational and unvalidated. It is not clinical advice or a clinical decision-making tool.

Current boundaries

Know what you’re
building on.

Version 0.1 is a working foundation with explicit limits. Treat production deployment and real-world compatibility as engineering work to validate.

Security & release boundaries

The gateway currently supports JSON metadata, reads, version reads, and searches. Clinical writes, arbitrary FHIR operations, and bulk export are future work.
Multi-server grants, full FHIR-version conversion, FHIRcast, SMART Web Messaging, and an independently conformant downstream SMART authorization server are future work.
Native URL dispatch and secure storage require platform integration; Android examples are illustrative adapters.
Live clinical data requires deployment-specific security review and vendor/customer validation.

Common questions

Before your first launch.

Is SMART Flint a FHIR server?

It is an integration service. Your organization’s FHIR server remains the source of clinical data. The optional gateway mediates supported reads and searches; it is not a general-purpose FHIR repository.

Do I have to replace my FHIR client or use an SDK?

No. The gateway uses ordinary FHIR HTTP responses and bearer authentication. Direct mode uses the original server and upstream access token. The SDKs are optional helpers for the lifecycle.

Does the local demo connect to Epic or Oracle Health?

The included vendor-labeled environments are synthetic simulators. Real vendor registration, customer enablement, and installation-specific validation are separate work. “Verified” discovery means metadata was checked, not that an end-to-end workflow is certified.

Can I deploy it in my own environment?

Yes. The guided installer supports a secured PostgreSQL deployment with local accounts or OIDC and existing or automatic HTTPS. The deployment guide covers both installer and manual Compose paths.

Can I use it commercially without paying?

Eligible business groups with annual gross revenue strictly below US$5 million can use it commercially under the Community License. At or above that threshold, a commercial agreement is required unless an exception applies. Read the full eligibility guide.

Ignite your app.Simplify the SMART.

The connection work.In one place.

Launch orchestration

Application-first configuration

Context & credential lifecycle

FHIR read/search gateway

SMART Backend Services

CDS Hooks forwarding

Administrative control

Self-hosted operations

SDKs, samples & a developer lab

Your application.Less integration plumbing.

One lifecycle.Three access models.

A launch. A callback.Your FHIR client.

Try the lifecycle.See the moving parts.

Know what you’rebuilding on.

Open the source.Make it your own.

Before your first launch.

Ignite your app.
Simplify the SMART.

The connection work.
In one place.

Your application.
Less integration plumbing.

One lifecycle.
Three access models.

A launch. A callback.
Your FHIR client.

Try the lifecycle.
See the moving parts.

Know what you’re
building on.

Open the source.
Make it your own.