Connecting your FHIR client with SMART Backend Services

Updated:


November 21, 2026

This guide is for teams whose software provider has offered them FHIR API access to health data, for example to feed an analytics platform, a data warehouse or a care-coordination tool. If that provider's app is built on Unified, your system reads the data through Unified's FHIR API, which serves standard HL7 FHIR R4 resources.

Your system signs in with SMART Backend Services, the standard for system-to-system access to FHIR servers. Instead of a password or a shared API key, it proves who it is with a private key that only you hold. No person needs to sign in, so it suits scheduled jobs and services.

๐Ÿ”‘ Use the SMART credentials your provider sets up for you. Your provider's own Unified API key gives access to all of its data, so it should never be shared with you, and you don't need it.

What you need

  • A SMART Backend Services client library, or any library that can sign JWTs (JSON Web Tokens). Most FHIR client libraries support SMART Backend Services.
  • A contact at your provider who can register your system.

1. Create a key pair

Create a key pair in your own system. Keep the private key secret: store it in a secrets manager and never send it to anyone, including your provider. You'll share only the public key.

The keys must be RSA (at least 2048 bits) or EC on the P-256 or P-384 curve, and you sign with RS384 or ES384. RS256 and ES256 also work. Many SMART libraries can create the keys for you. With OpenSSL, an EC P-384 key pair for ES384 looks like this:

openssl genpkey -algorithm EC -pkeyopt ec_paramgen_curve:P-384 -out private-key.pem
openssl pkey -in private-key.pem -pubout -out public-key.pem

2. Publish your public key set

Your provider needs your public key as a JSON Web Key Set (JWKS). Every key in it needs a key ID (kid), which you also put in each token request so the right key is used.

For example, with Node.js and the jose library:

import { readFileSync } from 'node:fs';
import { exportJWK, importSPKI } from 'jose';

const publicKey = await importSPKI(readFileSync('public-key.pem', 'utf8'), 'ES384');
const jwk = await exportJWK(publicKey);
console.log(JSON.stringify({ keys: [{ ...jwk, kid: 'key-1', alg: 'ES384', use: 'sig' }] }));

If you can, host the key set at an HTTPS URL, for example https://your-domain.example/.well-known/jwks.json. A hosted key set lets you rotate keys later without contacting your provider. If you can't host one, you can send your provider the key set as JSON instead.

3. Get your settings from your provider

Send your provider your key set URL (or the key set itself) and the FHIR resources you need, such as patients, observations or conditions. They'll send you back:

  • Client ID: identifies your system.
  • Token endpoint: where your system gets access tokens. It's one of:
    • https://api.unified.to/oauth/token
    • https://api-eu.unified.to/oauth/token
    • https://api-au.unified.to/oauth/token
  • FHIR base URL: one for each health system you can read, in the form https://api.unified.to/fhir/CONNECTION_ID (or on the EU or AU host).
  • Scopes: what you're allowed to read, for example system/Patient.rs system/Observation.rs. In each scope, r means read and s means search. Older SMART v1 scopes such as system/Patient.read also work.

Many SMART libraries only need the FHIR base URL and client ID. They find the token endpoint and supported scopes at FHIR_BASE_URL/.well-known/smart-configuration.

4. Get an access token

To get a token, your system signs a short JWT (the "client assertion") with its private key and exchanges it at the token endpoint. A SMART library does this for you. If you're building it yourself, the JWT needs:

  • iss and sub: your client ID.
  • aud: the token endpoint, exactly as your provider gave it.
  • jti: a new unique value for every request.
  • exp: no more than five minutes after the time it's signed.
  • In the header: alg (RS384, ES384, RS256 or ES256) and your key's kid.

For example, with Node.js and jose:

import { readFileSync } from 'node:fs';
import { randomUUID } from 'node:crypto';
import { SignJWT, importPKCS8 } from 'jose';

const CLIENT_ID = 'YOUR_CLIENT_ID';
const TOKEN_ENDPOINT = 'https://api.unified.to/oauth/token';

const privateKey = await importPKCS8(readFileSync('private-key.pem', 'utf8'), 'ES384');
const assertion = await new SignJWT({})
    .setProtectedHeader({ alg: 'ES384', kid: 'key-1', typ: 'JWT' })
    .setIssuer(CLIENT_ID)
    .setSubject(CLIENT_ID)
    .setAudience(TOKEN_ENDPOINT)
    .setJti(randomUUID())
    .setIssuedAt()
    .setExpirationTime('5m')
    .sign(privateKey);

const response = await fetch(TOKEN_ENDPOINT, {
    method: 'POST',
    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
    body: new URLSearchParams({
        grant_type: 'client_credentials',
        scope: 'system/Patient.rs system/Observation.rs',
        client_assertion_type: 'urn:ietf:params:oauth:client-assertion-type:jwt-bearer',
        client_assertion: assertion,
    }),
});
const { access_token, expires_in } = await response.json();

The response looks like this:

{ "access_token": "โ€ฆ", "token_type": "bearer", "expires_in": 300, "scope": "system/Patient.rs system/Observation.rs" }

You can ask for fewer scopes than you're allowed, but not more. Tokens last five minutes. Reuse a token until it's about to expire, then sign a new JWT, with a new jti, and get another.

5. Call the FHIR API

Send the token as a bearer token, and use your FHIR base URL:

# Search patients
curl "https://api.unified.to/fhir/CONNECTION_ID/Patient?_count=50" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

# Read one patient
curl "https://api.unified.to/fhir/CONNECTION_ID/Patient/PATIENT_ID" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

# Laboratory results for one patient
curl "https://api.unified.to/fhir/CONNECTION_ID/Observation?patient=PATIENT_ID&category=laboratory" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Searches return a FHIR Bundle. To get the next page, follow the Bundle's next link. To see which resources and search parameters a health system supports, read its CapabilityStatement at FHIR_BASE_URL/metadata.

Access is read-only: you can search and read resources, but not create, update or delete them.

Rotating keys

  1. Create a new key pair with a new kid.
  2. Add the new public key to your key set, keeping the old one for now.
  3. Switch your system to sign with the new key.
  4. Remove the old key from the key set.

With a hosted key set URL, that's all you need to do. If you sent your provider the key set as JSON, send them the updated set instead and wait until they confirm it's registered before switching keys.

Common errors and fixes

Token endpoint errors come back with an error code and an error_description.

  • invalid_client "unknown or disabled client": the client ID is wrong, or your provider has disabled your access. Contact your provider.
  • invalid_client "iss and sub must both be the client_id": set both claims to your client ID.
  • invalid_client with an aud error: set aud to the token endpoint, exactly as your provider gave it.
  • invalid_client "signature verification failed" or "no matching signing key": the JWT was signed with a key that isn't in your registered key set, or its kid doesn't match. Check that your key set URL is reachable and lists the key.
  • invalid_client "jti has already been used": use a new jti for every token request.
  • invalid_client "assertion lifetime must be at most 300 seconds" or "assertion expired": set exp no more than five minutes after iat, and check your server's clock.
  • invalid_scope: none of the scopes you asked for are allowed. Ask only for the system/ scopes your provider gave you.
  • 429 "rate limit exceeded": you're requesting tokens too often. Reuse each token for its five minutes.
  • 401 from the FHIR API: the token has expired or isn't valid. Get a new one.
  • 403 OperationOutcome "forbidden": your token doesn't include that resource. Ask your provider to allow it, then get a new token.
  • 403 "may not access this connection": you don't have access to that health system. Check the FHIR base URL, or ask your provider to add it.
  • 403 "IP address rejected": your provider only accepts calls from approved IP addresses. Send them your system's outgoing IP addresses.
  • 403 insufficient_scope: SMART tokens only work on the FHIR API. Use the FHIR base URL your provider gave you.

Learn more

Share
All guidesAccounting Account Type Hierarchy in UnifiedAdvertising Report Metrics by IntegrationAmazon S3: Required IAM PermissionsATS to Vector DB: How to Power Talent Intelligence with Real-Time DataBuilding AI applications with Unified and LangbaseConcur & Concur (Company) โ€” Connection GuideConfigure Greenhouse Native Candidate WebhooksConfigure Salesforce Meetings and Notes for UnifiedConnect Amazon Seller Central to Unified.toConnecting BambooHR via OAuth 2Connecting Google Workspace Integrations with a Service AccountCorrect WelcomeKit Scopes for Jungle IntegrationCreating Ads using the Unified Ads APICreating Walmart Items via UnifiedEnd-Users, Integrations, and ConnectionsEnriching Unified Objects with Custom MetadataEnterprise-managed authorization (EMA) with a static keyEnterprise-managed authorization (EMA) with a workspace secretEnterprise-managed authorization (EMA) with Microsoft Entra IDExtended observability: pushing API logs to a syslog serverExtended observability โ€” pushing API logs to ClickHouseExtended observability โ€” pushing API logs to Grafana / LokiExtended observability: pushing API logs to SplunkExtended Observability - Pushing API Logs to your Datadog InstanceFacebook Messenger Webhook SetupFHIR API authentication: API keys and SMART Backend ServicesFireflies Integration GuideGetting started with WorkableHandling Delegated vs. Application Scopes in Microsoft IntegrationsHiBob & Unified: connection and time off guideHow long are logs retainedHow to access employees and usersHow to add API support for the Create Activity in CrelateHow to Associate a Connection ID with Your End-UserHow to build a Candidate Assessment product with UnifiedHow to build a candidate sourcing or job board app with Unified.toHow to build a Discord support bot with Unified.to and LangbaseHow to Build a Fintech Application with Unified's Payments APIHow to Build an E-Commerce Product Integration with UnifiedHow to build an invoicing system with Unified.toHow to build Enterprise Search using RAGHow to configure Bullhorn Redirect URI for creating a connectionHow to configure webhooks in HubSpotHow to configure webhooks in Thrive LearningHow to configure webhooks in Toast for UnifiedHow to Connect Anthropic to Real-Time SaaS Data with Unified.to MCP ServerHow to Connect Cohere to Real-Time SaaS Data with Unified.to MCP ServerHow to Connect Google Gemini to Real-Time SaaS Data with Unified.to MCP ServerHow to connect HiBob (Bob) to Unified with OAuth 2.0How to Connect LLMs to Real-Time SaaS Data with Unified.to MCP ServerHow to Connect OpenAI to Real-Time SaaS Data with Unified.to MCP ServerHow to Connect Zoom and Zoom PhoneHow to create a Connection In Microsoft TeamsHow to create a token-based connection in HighlevelHow to Create a Unified.to Connection to HighLevelHow to Create a Xero Connection in Unified.toHow to create and configure webhooksHow to create Connection with HubspotHow to customize portal URLs for Stripe and GoCardlessHow to filter webhook eventsHow-to Get a Private Support Channel for Your Unified IntegrationHow to get help from Unified.toHow to get your 8x8 Connect API Key, Account ID and SMS Subaccount ID (optional): Step-by-step guideHow to get your ADP Workforce Now Oauth2 client ID, Oauth2 client secret, Oauth2 PEM certificate and Oauth2 private key: Step-by-step guideHow to get your Amazon S3 AWS Region, AWS S3 Key, AWS S3 Secret and AWS S3 Bucket(s) (optional, comma-separated): Step-by-step guideHow to get your Ashby API Key: Step-by-step guideHow to get your Brex API token: Step-by-step guideHow to get your Bullhorn OAuth2 Client ID, OAuth2 Client Secret, API Username and API Password: Step-by-step guideHow to get your Ceridian Dayforce Username, Password and Client Namespace: Step-by-step guideHow to get your Crelate API key: Step-by-step guideHow to get your Dashlane API Key: Step-by-step guideHow to get your Deel Access Token: Step-by-step guideHow to get your Dialpad API Key: Step-by-step guideHow to get your Discord OAuth 2 credentials and bot tokenHow to get your ELMO client ID and client secret: Step-by-step guideHow to get your Gainsight Client ID, Client Secret and Gainsight API Domain: Step-by-step guideHow to get your Greenhouse API Key and Job board token: Step-by-step guideHow to get your Helpscout API Key: Step-by-step guideHow to get your HiBob Service User ID and Service User Token: Step-by-step guideHow to get your HighLevel API Key and Location ID: Step-by-step guideHow to get your HubSpot developer key and OAuth 2 credentials (Legacy Apps)How to get your Humaans API Key: Step-by-step guideHow to get your iCIMS API Username, API Password and Customer ID: Step-by-step guideHow to get your JobDiva Client ID, Username/email and Password: Step-by-step guideHow to get your Jobvite API Key, API Key Secret and Email: Step-by-step guideHow to get your Lever API Key: Step-by-step guideHow to get your Loxo Agency slug, API Key and Agency ID: Step-by-step guideHow to get your Microsoft Active Directory / Entra ID Client ID, Client Secret and Tenant ID: Step-by-step guideHow to get your Microsoft Azure AD OAuth 2 credentialsHow to get your OAuth 2 credentials for GmailHow to get your OAuth 2 credentials for Microsoft Dynamics 365How to get your OAuth 2 credentials in PipeDriveHow to get your OpenAI API Key: Step-by-step guideHow to get your Paycom SID/Username and Token/Password: Step-by-step guideHow to get your PCRecruiter Username, Password, Database ID, App Key and App ID: Step-by-step guideHow to get your SAP SuccessFactors (OpenID Connect) Username, Password, Client ID, Client Secret, Dependency Name, IAS Host and API URL: Step-by-step guideHow to get your SAP SuccessFactors Username, Company ID, Password and API URL: Step-by-step guideHow to get your Shopify Admin API access token and Store ID: Step-by-step guideHow to get your Wayfair Client ID, Client Secret and Vendor Encrypted Key: Step-by-step guideHow to get your Workable API Token and Subdomain: Step-by-step guideHow to get your yotpo APP Key / Store ID and Secret Key: Step-by-step guideHow to Handle Attachments in Invoice, Bill and Credit MemoHow to Manage Google Ad Manager Orders, Line Items and Creatives with the Unified.to Advertising APIHow to migrate or import your integrations into Unified.toHow to obtain your GitHub OAuth2 credentialsHow to Power Claude with Live Customer Data Using Unified MCPHow to receive assessment orders from an ATS with Unified.toHow to register a Google developer app and get OAuth 2 credentialsHow to Register a HiBob Developer App and Get OAUTH2 CredentialsHow to register a Salesforce developer app and get OAuth 2 credentialsHow to register a Slack developer account and get OAuth 2 credentialsHow to Register a Workday Developer App and Get OAUTH2 CredentialsHow to Register a Workday Developer App and Get OAUTH2/ SOAP CredentialsHow to Register a ZendeskSell Developer App and Get OAUTH2 CredentialsHow to Register a Zoho Developer App and Get OAUTH2 CredentialsHow to Register an ADP Developer App and Get OAUTH2 CredentialsHow to Register an Atlassian Developer App and Get OAUTH2 CredentialsHow to Register your Facebook OAuth2 ApplicationHow to Register your Google Ads OAuth2 ApplicationHow to Register your MetaAds OAuth2 applicationHow To Request & Write Raw Integration DataHow to Retrieve Microsoft Dynamics 365 Business Central CredentialsHow to set up a custom API URL with a CNAMEHow to Set Up a Google Meet Meeting Bot with UnifiedHow to set up a HiBob marketplace installHow to Set Up a Microsoft Teams Bot with UnifiedHow to Set Up a Microsoft Teams Meeting Bot with UnifiedHow to Set Up a Webex Meeting Bot with UnifiedHow to Set Up a Zoom Meeting Bot with UnifiedHow to set up and configure NotionHow to set up Google Business Profile API access and get OAuth 2 credentialsHow to Set Up LinkedIn Webhooks with UnifiedHow to set up native webhooks for QuickBooks Online with UnifiedHow to set up Slack webhooks using event subscriptionsHow to set up Telegram (bot) with Unified.toHow to set up your scopes in HubSpotHow to setup a Freshbooks developer appHow to setup a TikTok Shop applicationHow to Setup AWS Assume Role for AWS Secret ManagerHow to setup Oracle JD EdwardsHow to Setup Quickbooks DesktopHow to setup Sage 100 with Unified.toHow to test webhooks in the Synthetic Data (Sandbox) environmentHow to troubleshoot unhealthy connectionsHow to troubleshoot unhealthy webhooksHow to Use Decision Models with the Unified GenAI APIHow to use SCIM with the Unified APIHow to use the Passthrough APIHow to Use Unified.to's Generative AI API with OpenAI and ClaudeHow to use User Provisioning and Verification with UnifiedHow virtual webhook retry and recovery worksIntegration set-up guide for LeverManaging custom validation rules in SalesforceNetSuite Authentication Setup for UnifiedNotice of Deprecation of Fields and Objects (Nov 2025)Oracle HCM / Taleo OAuth Credentials GuideRetrieval-Augmented Generation (RAG)SalesForce (External Client Apps) on Multiple OrganizationsSAML Single-Sign-OnScaling MCP Tools with Anthropic's (& OpenAI's) Defer LoadingScaling MCP Tools with Anthropic's Programmatic Tool CallingSet Environments for your Unified.to WorkspaceSetting up a Slack Bot Connection with Unified.toSetting up OAuth 2 Credentials for Greenhouse's APIsTrello Connection Guide in UnifiedUnderstanding OAuth2 Authorization flowsUnderstanding Response Time Headers in the Unified APIUnified Assessment API: Embed Assessments Inside ATS PlatformsUnified's MCP ServerUnified MCP Server with LangChain and LangGraphUnlock real-time data with virtual webhooksUse Unified to sign in your users into your applicationVincere OAuth Setup Guide for UnifiedWhy you can't use Unified's OAuth2 credentials to authorize your end users on ProductionWorkable: Creating candidates and attaching them to jobsWorkday vs Workday Legacy โ€” Why Unified.to Supports BothWorking with hierarchical tree data in Storage, Messaging, and KMS APIs
Are we missing anything? Let us know
Was this page helpful?