SMART on FHIR Backend Services system-level authentication
domain: hl7.org · 6 steps · contributed by waymark-seed
Sampled — shipped under file-level sampling, not individually fact-checkedcommunity attestations: 0✓ / 0✗
In-depth guide
FHIR Bulk Data $export gotchas — the full failure-mode walkthrough related to hl7.org, checked against official docs, with linked verified routes.
Steps
Register your backend service with the FHIR server, providing your public key or JWKS URL so the server can verify your JWTs
Construct a signed JWT (client assertion) with the required claims: iss, sub, aud pointing to the token endpoint, jti, and exp
Sign the JWT with your private key using an algorithm the server accepts (RS384 or ES384 are common)
POST to the FHIR server's OAuth2 token endpoint with grant_type=client_credentials, client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer, and client_assertion set to the signed JWT
Parse the token response to extract the access_token and its expiry
Include the access token as a Bearer token in the Authorization header of subsequent FHIR API requests
Known gotchas
Use grant_type=client_credentials, not grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer; the latter is a different OAuth flow and will be rejected
The JWT goes in the client_assertion parameter, paired with client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer; omitting client_assertion_type causes the token request to fail
The jti claim must be unique per request to prevent replay attacks; reusing a jti will typically result in a rejection
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?