---
title: "FHIR API authentication: API keys and SMART Backend Services"
img: https://s3.us-east-2.amazonaws.com/unified-article-images/fhir_api_authentication_api_keys_and_smart_backend_services-icon.png
date: 2026-11-21T00:25:00.000Z
updated: "2026-11-21T00:45:58.832Z"
tag: Guides
integrations: 
description: "Unified's FHIR API serves data from your Healthcare connections as standard HL7 FHIR R4 resources. There are two ways to authenticate to it,"
url: "https://docs.unified.to/guides/fhir_api_authentication_api_keys_and_smart_backend_services"
---

# 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.

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:

```bash
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](https://app.notion.com/p/41f6207b838481858acbc00e668086e6) 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:


```bash
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](https://app.notion.com/p/41f6207b838481858acbc00e668086e6).


## 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](https://app.notion.com/p/4136207b838481d6b0b4e78ab5d5edff).
- SMART clients and their tokens belong to one region (US, EU or AU), like the rest of your workspace.

## Learn more

- [FHIR API documentation](https://docs.unified.to/fhir/overview)
- [SMART Backend Services specification (HL7)](https://hl7.org/fhir/smart-app-launch/backend-services.html)