---
title: "Connecting your FHIR client with SMART Backend Services"
img: https://s3.us-east-2.amazonaws.com/unified-article-images/connecting_your_fhir_client_with_smart_backend_services-icon.png
date: 2026-11-21T00:38:00.000Z
updated: "2026-11-21T00:45:57.793Z"
tag: Guides
integrations: 
description: "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..."
url: "https://docs.unified.to/guides/connecting_your_fhir_client_with_smart_backend_services"
---

# Connecting your FHIR client with SMART Backend Services
------
_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:


```bash
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:


```javascript
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`:


```javascript
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:


```json
{ "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:


```bash
# 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

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