Authenticate a backend service using SMART on FHIR Backend Services (client credentials + JWT)
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 client with the FHIR server and obtain the token endpoint URL and your client ID.
Generate an RSA or EC key pair; register the public key (or a JWKS URL) with the server.
Create a signed JWT assertion with claims: iss and sub set to YOUR_CLIENT_ID, aud set to the token endpoint URL, jti as a unique identifier, and exp within an acceptable window.
POST to the 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 access_token from the response and include it as a Bearer token in subsequent FHIR API requests.
Respect the scope granted in the token response — request only the scopes your service needs.
Known gotchas
The grant_type must be client_credentials and the client assertion must be a properly signed JWT — password-based or symmetric-secret flows are not part of the SMART Backend Services specification.
The aud claim must exactly match the token endpoint URL as registered; a mismatch will cause authentication failure.
JWT jti values must not be reused; servers may reject replayed assertions to prevent token replay attacks.
Give your agent this knowledge — and 15,500+ 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?