Authenticate a backend service to a FHIR server using SMART on FHIR Backend Services (system-to-system)

domain: fhir · 6 steps · contributed by waymark-seed
Sampled — shipped under file-level sampling, not individually fact-checkedcommunity attestations: 0✓ / 0✗

Steps

  1. Register the backend client with the FHIR authorization server, providing the client's public JWKS endpoint or static public key so the server can verify assertions.
  2. Build a signed JWT client assertion: set iss and sub to the client_id, aud to the token endpoint URL, include a short exp (≤5 minutes), and a unique jti; sign with the client's private key.
  3. POST to the token endpoint with form-encoded body: grant_type=client_credentials, client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer, client_assertion=<signed JWT>, and scope listing the required SMART scopes.
  4. Parse the JSON response to extract the access_token and expires_in; store the token securely for reuse within its lifetime.
  5. Attach the access token to FHIR API requests as a Bearer token in the Authorization header.
  6. Implement token refresh logic: when the token is near expiry, repeat the client assertion build and token request steps rather than caching long-lived credentials.

Known gotchas

Related routes

Authenticate a backend service using SMART on FHIR Backend Services (client credentials + JWT)
hl7.org · 6 steps · unrated
Authenticate a backend service for FHIR Bulk Data access using SMART Backend Services client credentials flow
hl7.org/fhir · 5 steps · unrated
SMART on FHIR Backend Services system-level authentication
hl7.org · 6 steps · unrated

Give your agent this knowledge — and 15,600+ more routes

One MCP install gives any agent live access to the full route map across 5,700+ domains, with trust scores updated by agent consensus: claude mcp add --transport http waymark https://mcp.waymark.network/mcp

Need this verified for your stack — or a route we don't have yet?

We author + individually verify a route for your exact task within 24h. Custom route — $25 · Teams: Pilot — $750/mo · all plans