The server-side half of @fhirstarter: a SMART on FHIR Backend Services
(client credentials) auth engine. It owns the JWT client assertion, JWKS
derivation, and a proactive refresh loop that keeps a valid token ready at all
times, then stays out of your way. Because it never touches FHIR itself, the
result is a flat handoff you spread into whatever client you already use:
FHIR.client(auth.fhirClient), auth.authHeaders for fetch, or
auth.onRefresh(...) to feed fhir-kit-client.
Launching from an EHR instead? See the sister project @fhirstarter/ehr, a turnkey SMART EHR-launch wrapper with Vue/React components.
- Install
- Usage
- Other FHIR clients
- API
- Thumbprint
- JWKS
- Key rotation
- Shared token store
- Transport & retries
- Events
- Validation
- Compatibility
- Scripts
- Notes
npm install @fhirstarter/backendThis example uses the official fhirclient package as the FHIR client;
fhirStarter only manages auth.
import FHIR from "fhirclient"
import fhirStarter from "@fhirstarter/backend"
const auth = await fhirStarter({
serverUrl: "https://fhir.epic.com/interconnect-fhir-oauth/api/FHIR/R4",
clientId: "your-client-id",
privateKey: process.env.FHIR_PRIVATE_KEY!, // base64-encoded PKCS#8 PEM
tokenEndpointUrl: "https://fhir.epic.com/interconnect-fhir-oauth/oauth2/token",
scopes: ["system/Patient.rs", "system/Observation.rs"],
})
const client = FHIR.client(auth.fhirClient)
const bundle = await client.request("Patient?family=Smith")await fhirStarter(config) fetches the first token, starts the proactive refresh
loop, and resolves to a ready provider; it rejects if config is invalid or the
first token request fails. auth.fhirClient is a ready-to-spread FHIR.client(...)
argument built from your serverUrl and a live tokenResponse, so fhirclient
always reads the latest token per request.
fhirStarter does not fetch FHIR resources and does not bundle a FHIR client. It
manages authentication and refresh; the FHIR client does the rest.
privateKey can be PKCS#8 PEM text, a Buffer, or a base64-encoded PEM string
(the preferred form for environment variables). File paths are not supported.
For raw fetch or any HTTP client, spread the current auth headers:
const res = await fetch(`${auth.serverUrl}/Patient?family=Smith`, {
headers: auth.authHeaders,
})auth.authHeaders is { Authorization: "Bearer <token>" } when a valid token is
cached, or {} otherwise. Read it per request so it always reflects the latest
token. auth.accessToken and auth.expiresAt (epoch ms) expose the raw values.
For clients with a bearer token setter (e.g. fhir-kit-client):
const unsubscribe = auth.onRefresh((token) => {
client.bearerToken = token
})await fhirStarter(config) resolves to a ready provider (no new)
| Member | Returns | Description |
|---|---|---|
serverUrl |
string |
FHIR base URL from config |
accessToken |
string | null |
Current valid token, or null if expired |
expiresAt |
number | null |
Epoch ms of actual expiry, or null |
token |
string | null |
Alias of accessToken |
expiresIn |
number | null |
Seconds until actual expiry, or null |
authorizationHeader |
string | null |
Bearer <token> or null |
getAccessToken() |
Promise<string> |
Async valid token with lazy refresh |
applyScopes(scopes) |
Promise<string> |
Re-acquire with a new scope set now; adopted only on success (refresh is otherwise automatic) |
tokenResponse() |
LiveTokenResponse |
Getter-backed token response for fhirclient |
fhirClient |
FhirClientState |
Spread into FHIR.client(...); writable outer, live token |
authHeaders |
AuthHeaders |
{ Authorization } for fetch, or {} when no token |
onRefresh(callback) |
() => void |
Subscribe to token re-acquisitions; returns unsubscribe |
onRefreshStart(callback) |
() => void |
Fires when a token request begins |
onRefreshEnd(callback) |
() => void |
Fires when a token request ends (success or failure) |
onError(callback) |
() => void |
Fires on failure with a redacted RefreshError |
fhirStarter.thumbprint(privateKey) |
string |
RFC 7638 JWK Thumbprint (base64url SHA-256) |
fhirStarter.memoryStore() |
TokenStore |
Single-process reference token store (handy for tests) |
fhirStarter.validate(config) |
ValidationResult |
Offline config check returning { ok, problems } (no network) |
fhirStarter.getJwks(config) |
Promise<JwkSet> |
Public JWKS from a private-key config (offline, no token request) |
fhirStarter.getJwks(config) strips private key material; host the output JSON at
your registered JWKS URL and pass that URL as jwksUrl so the JWT jku header is
set automatically. It runs offline but still expects a complete private-key config.
Derive a deterministic kid from a private key without instantiating the class:
import fhirStarter from "@fhirstarter/backend"
const kid = fhirStarter.thumbprint(pemOrBuffer)
console.log(kid) // base64url SHA-256 of the canonical public JWK (RSA or EC)This implements RFC 7638: the SHA-256 of the sorted canonical JWK members
({e, kty, n} for RSA, {crv, kty, x, y} for EC), base64url-encoded. Use it as
the keyId when registering your JWKS.
Some SMART Backend Services registrations require a public JWKS URL when using
jku. Generate it from the same private key you use for auth:
import { writeFileSync } from "node:fs"
import fhirStarter from "@fhirstarter/backend"
// Offline static: no provider, no token request.
const jwks = await fhirStarter.getJwks({
serverUrl: "https://fhir.example/r4",
clientId: "your-client-id",
privateKey: process.env.FHIR_PRIVATE_KEY!, // base64-encoded PKCS#8 PEM
tokenEndpointUrl: "https://fhir.epic.com/interconnect-fhir-oauth/oauth2/token",
scopes: ["system/Patient.rs"],
keyId: "my-key-id",
jwksUrl: "https://example.com/.well-known/jwks.json",
})
writeFileSync("./jwks.json", JSON.stringify(jwks, null, 3))Host jwks.json at the exact URL you register with your authorization server,
then pass that URL as jwksUrl. If you set keyId, the generated key includes
kid, and signed JWTs use the same kid header. If you omit keyId, the kid
defaults to the key's RFC 7638 thumbprint.
To rotate without downtime, publish the new key alongside the old one during an
overlap window. Set the new key as privateKey (signing switches to it
immediately) and list the previous key in retiredKeys so
fhirStarter.getJwks(config) keeps publishing its public JWK for verifiers that
cached the old JWKS:
const auth = await fhirStarter({
serverUrl: "https://fhir.example/r4",
clientId: "your-client-id",
privateKey: process.env.FHIR_NEW_KEY!, // active, signs all assertions
retiredKeys: [process.env.FHIR_OLD_KEY!], // publish-only, never signs
tokenEndpointUrl: "https://auth.example/token",
scopes: ["system/Patient.rs"],
})Sequence: publish the successor in JWKS → wait through the JWKS cache lifetime →
make it active → keep the retired key through the cache lifetime plus the max
assertion lifetime (5 min), then drop it from retiredKeys. Each key is
published under its own kid (its thumbprint unless overridden).
If a retired key was published under a custom kid while active, pass it as a
{ key, keyId } pair so fhirStarter.getJwks(config) republishes it under the
same kid (otherwise it falls back to the thumbprint):
retiredKeys: [{ key: process.env.FHIR_OLD_KEY!, keyId: "old-kid" }],By default each provider refreshes independently. When you run several processes
under the same client identity, pass a tokenStore so they coordinate: only one
process fetches a token at a time (via an owner-scoped lease) and the others
adopt the shared result, avoiding refresh storms.
const auth = await fhirStarter({
serverUrl: "https://fhir.example/r4",
clientId: "your-client-id",
privateKey: process.env.FHIR_PRIVATE_KEY!,
tokenEndpointUrl: "https://auth.example/token",
scopes: ["system/Patient.rs"],
tokenStore: myRedisStore, // implements the TokenStore interface
})fhirStarter.memoryStore() is a single-process reference implementation (handy
for tests). For real multi-process coordination, supply a store backed by Redis,
a database, or similar. The store contract requires atomic, owner-scoped leases
and a setUnderLease that writes only while the caller still holds the lease.
Token requests retry transient failures with exponential backoff and jitter.
Only network errors and HTTP 408/429/5xx are retried; permanent 4xx such as
invalid_client or invalid_scope fail immediately. A Retry-After header is
honored when present. Each retry builds a fresh JWT assertion (new jti).
Tune via config: timeoutMs (per-attempt, default 30000), maxAttempts
(default 3), and backoffMs (base delay, default 500).
onRefresh(cb) fires on every successful token acquisition after the first
(including a token adopted from a shared store), not on the initial acquisition
or a late subscription. Use it to push tokens into clients that cache them:
auth.onRefresh((token) => (client.bearerToken = token))onRefreshStart / onRefreshEnd bracket each token acquisition attempt;
onError delivers a redacted RefreshError ({ message, status? }) that never
contains tokens or secrets. Subscriptions observe attempts after the provider
resolves; initial failures reject fhirStarter(config). All four return an
unsubscribe function, and listener exceptions never break refresh handling.
fhirStarter.validate(config) runs a fast, offline check of the config: HTTPS
FHIR and token endpoints, non-empty scopes, key parsing, supported algorithm
(RS384/ES384), and unique kids across active and retired keys. It makes no
network calls and returns { ok, problems }:
const { ok, problems } = fhirStarter.validate(config)
if (!ok) throw new Error(`Invalid config: ${problems.join("; ")}`)Actual credential/scope acceptance can only be proven by a real token request,
so treat a successful await fhirStarter(config) as the true integration check.
fhirClient and tokenResponse() are designed for fhirclient.request(), which
reads the token per request. If a client copies the token at construction time
instead, use onRefresh() to update or recreate that client. If fhirclient
clears its internal state after a 401, recreate the client with auth.fhirClient.
| Command | What |
|---|---|
npm run check |
tsc --noEmit |
npm run build |
Compile to dist/ |
await fhirStarter(config)fetches the first token and begins the proactive refresh loop automatically; the resolved provider is ready to use- Tokens are cached with separate refresh and expiry timestamps; if a refresh fails but the token is not yet expired, the old token remains usable
- Concurrent callers share a single in-flight token refresh
- JWT assertions are signed RS384 (RSA) or ES384 (P-384 EC), expire after 5 minutes
- Requires Node 20+, a PKCS#8 RSA or P-384 EC key, and SMART Backend Services scopes