Obtain a system-level FHIR access token using SMART Backend Services client credentials flow
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 by providing your public JWK or JWKS URL out-of-band
Generate a signed JWT client assertion using your private key, setting iss and sub to your client_id, aud to the token endpoint URL, and including jti and exp claims
POST to the token endpoint with Content-Type application/x-www-form-urlencoded and the following parameters: grant_type=client_credentials, client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer, client_assertion=<your signed JWT>, and scope=<requested FHIR scopes>
Parse the access_token and expires_in from the JSON response
Include the access token as a Bearer token in the Authorization header of all subsequent FHIR API requests
Re-authenticate before expiry; do not cache tokens beyond their expires_in window
Known gotchas
The client_assertion_type value must be exactly urn:ietf:params:oauth:client-assertion-type:jwt-bearer — using any variation such as grant-assertion instead of client-assertion-type will cause the token request to fail
SMART Backend Services does not involve a user; there is no authorization_code step — the entire flow is server-to-server using client_credentials
The jti claim in the client assertion JWT must be unique per request to prevent replay attacks; many FHIR servers enforce this strictly
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?