FHIR API authentication: API keys and SMART Backend Services

Updated:


November 21, 2026

Unified's FHIR API serves data from your Healthcare connections as standard HL7 FHIR R4 resources. There are two ways to authenticate to it:

  • Your workspace API key, for your own backend. It's the same key you use for every other Unified API.
  • SMART Backend Services, for your customers' systems. Each customer gets their own SMART client, and their system signs in with its own private key, limited to the data you choose.

Which one to use

Workspace API keySMART Backend Services
Who uses itYour own serversYour customers' systems, such as their analytics platform or data warehouse
What it can reachEvery Unified API and every connection in your workspaceOnly the FHIR API, only the connections and resources you allow, read-only
How it signs inSends the key on every requestSigns a short request with its private key and gets a token that lasts five minutes
Works with standard SMART client librariesNoYes
Never give your API key to a customer. It gives full access to your workspace, including every other customer's data. Give customers a SMART client instead.

Option 1: Use your workspace API key

Use this when your own backend reads FHIR resources, for example to show them in your app or pass them on to another system you run.

  1. In the dashboard, go to Settings → API Keys and copy your key. Store it in a secrets manager on your servers, never in browser or mobile code.
  2. Send it as a bearer token, with the FHIR base URL of a connection:
curl "https://api.unified.to/fhir/CONNECTION_ID/Patient?_count=50" \
  -H "Authorization: Bearer $UNIFIED_API_KEY"

The FHIR base URL for each connection is https://api.unified.to/fhir/CONNECTION_ID. Use api-eu.unified.to or api-au.unified.to if your workspace is in the EU or AU region.

Option 2: Give your customers SMART Backend Services access

Use this when your customers want their own systems to read the health data they've connected through your app.

How it works

  1. Your customer connects their EHR or other healthcare system through your app, as usual. This creates a connection in your workspace.
  2. Your customer creates a key pair and gives you the public key. The private key never leaves their system.
  3. You register a SMART client for them, limited to their connections and to the FHIR resources they need.
  4. You send them their settings: the client ID, the token endpoint and their FHIR base URL.
  5. Their system signs a token request with its private key, gets an access token that lasts five minutes, and reads FHIR resources with it.

SMART tokens can only read and search FHIR resources. They work on the FHIR API and nowhere else, so they can't manage your workspace or reach other Unified APIs. To manage SMART clients you need workspace admin access.

Share Connecting your FHIR client with SMART Backend Services with your customers. It walks them through creating keys, getting tokens and calling the API.

Collect your customer's public keys

The keys must be:

  • RSA, at least 2048 bits, or EC on the P-256 or P-384 curve.
  • Usable with RS384 or ES384, the algorithms SMART recommends. RS256 and ES256 also work.
  • Public keys only, each with a key ID (kid). Never accept or paste a private key.

A key set URL that serves a JSON Web Key Set (JWKS) is the better choice where your customer can host one. Unified fetches it over HTTPS and picks up rotated keys automatically, so your customer can change keys without contacting you. If they can't host one, they can send you the key set as JSON instead.

Register a SMART client

In the dashboard:

  1. Go to Settings → FHIR SMART clients and click Add SMART client.
  2. Enter a Name that identifies your customer, for example their company name.
  3. Under How to provide the public keys, choose Key set URL and enter it, or choose Paste key set and paste the JSON.
  4. Under Allowed scopes, enter the FHIR resources this customer may read (see Choosing scopes below). Leave it empty to allow read and search on every resource.
  5. Under Connections the client can read, tick your customer's own connections. Always do this when you serve more than one customer. If you leave them all unticked, the client can read every Healthcare connection in your workspace.
  6. Optionally pick an Environment, so the client only reaches connections in that environment.
  7. Click Add client and copy the Client ID.
  8. Click Test keys on the client's row to check that its keys load and see which signing algorithms are usable.

You can also register clients from your own app, for example as part of customer onboarding, using a workspace admin's API key:

curl -X POST https://api.unified.to/unified/fhir/smart-clients \
  -H "Authorization: Bearer $UNIFIED_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Analytics",
    "jwks_uri": "https://keys.example.com/.well-known/jwks.json",
    "allowed_scopes": ["system/Patient.rs", "system/Observation.rs"],
    "connection_ids": ["YOUR_CUSTOMERS_CONNECTION_ID"]
  }'

The response includes the client_id. To send the key set itself instead of a URL, replace jwks_uri with jwks.

Choosing scopes

Scopes use the SMART system/ form, one per FHIR resource:

  • system/Patient.rs: read (r) and search (s) patients. Use .r or .s alone to allow just one of them.
  • system/*.rs: read and search every resource the FHIR API serves.
  • The older SMART v1 form also works, for example system/Patient.read.

Grant only what your customer needs. Their system can ask for fewer scopes when it requests a token, but never for more than the client allows. Write scopes and patient or user scopes (patient/…, user/…) are never granted.

Send your customer their settings

  • Client ID: the client_id of their SMART client.
  • Token endpoint for your region:
    • US: https://api.unified.to/oauth/token
    • EU: https://api-eu.unified.to/oauth/token
    • AU: https://api-au.unified.to/oauth/token
  • FHIR base URL, one for each of their connections: https://api.unified.to/fhir/CONNECTION_ID, on your region's host.
  • Scopes they're allowed, for example system/Patient.rs system/Observation.rs.

Managing SMART clients

  • Rotate keys: with a key set URL, your customer publishes the new key there and Unified picks it up. With a pasted key set, edit the client and paste the new set.
  • Change access: edit the client to change its scopes, connections or environment. Saving new keys, scopes, connections or an environment ends the client's current tokens, and its next token follows the new settings.
  • Pause access: click Disable. Current tokens stop working at once, and the client can't get new ones until you enable it again.
  • Remove access: click Delete. This also ends current tokens and can't be undone.
  • Check activity: the clients list shows when each client last got a token.

When a customer adds another connection, edit their client and tick the new connection too.

IP allowlist

If your workspace has an IP allowlist, it applies to FHIR API calls made with your API key and with SMART tokens. Add your customers' outgoing IP addresses, or their calls are refused with 403 IP address rejected.

Common errors and fixes

  • 401 with your API key: the key is missing, mistyped or no longer valid. Copy it again from Settings → API Keys.
  • 403 "IP address rejected": the call came from an address that isn't on your workspace IP allowlist.
  • 403 "may not access this connection" (SMART): the connection isn't ticked under Connections the client can read.
  • 403 OperationOutcome "forbidden" (SMART): the resource isn't in the client's allowed scopes. Add it, then your customer requests a new token.
  • 403 insufficient_scope (SMART): SMART tokens only work on the FHIR API.
  • invalid_client "unknown or disabled client" (SMART): the client ID is wrong, or the client is disabled or deleted.
  • invalid_client "signature verification failed" or "no matching signing key" (SMART): the customer signed with a key that isn't in the registered key set. Check it with Test keys.

For other token errors your customer may see, see Connecting your FHIR client with SMART Backend Services.

Limits

  • The FHIR API is read-only: search and read. Create, update and delete aren't available.
  • On the FHIR API, SMART supports Backend Services (system-to-system) only. A patient or clinician can't sign in to it directly. To connect your app to an EHR's own SMART on FHIR server, see Connecting healthcare systems with SMART on FHIR.
  • SMART clients and their tokens belong to one region (US, EU or AU), like the rest of your workspace.

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 AccountConnecting your FHIR client with SMART Backend ServicesCorrect 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 SetupFireflies 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?