FHIR API authentication: API keys and SMART Backend Services
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 key | SMART Backend Services | |
|---|---|---|
| Who uses it | Your own servers | Your customers' systems, such as their analytics platform or data warehouse |
| What it can reach | Every Unified API and every connection in your workspace | Only the FHIR API, only the connections and resources you allow, read-only |
| How it signs in | Sends the key on every request | Signs a short request with its private key and gets a token that lasts five minutes |
| Works with standard SMART client libraries | No | Yes |
| 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.
- 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.
- 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
- Your customer connects their EHR or other healthcare system through your app, as usual. This creates a connection in your workspace.
- Your customer creates a key pair and gives you the public key. The private key never leaves their system.
- You register a SMART client for them, limited to their connections and to the FHIR resources they need.
- You send them their settings: the client ID, the token endpoint and their FHIR base URL.
- 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:
- Go to Settings → FHIR SMART clients and click Add SMART client.
- Enter a Name that identifies your customer, for example their company name.
- Under How to provide the public keys, choose Key set URL and enter it, or choose Paste key set and paste the JSON.
- 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.
- 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.
- Optionally pick an Environment, so the client only reaches connections in that environment.
- Click Add client and copy the Client ID.
- 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.ror.salone 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_idof 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
- US:
- 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
401with 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.403OperationOutcome "forbidden" (SMART): the resource isn't in the client's allowed scopes. Add it, then your customer requests a new token.403insufficient_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.