Implementation Guide
This guide walks your EHR IT team through the steps required to install the VectorCare SMART on FHIR application in your EHR. For background on the SMART on FHIR standard, see What is SMART on FHIR?.
Prerequisites
Before beginning, confirm that your EHR meets the following requirements:
- SMART on FHIR — Your EHR must support the SMART App Launch framework, and must implement the
/.well-known/smart-configurationdiscovery endpoint. - FHIR R4 — Your EHR must expose a FHIR R4-compliant REST API.
- Authorization server — Your EHR's authorization server must support
private_key_jwtclient authentication (our app is a Confidential Client), JWKS-based public key validation, and refresh tokens.
Confirm FHIR APIs
The app requires the following FHIR R4 APIs (all read-only). Ensure these are available in your EHR.
Required:
| Enabled API | Usage |
|---|---|
| Patient.Read (Demographics) | Demographics, identifiers (MRN) |
| Practitioner.Read | Current user identity |
Optional — these pre-populate Service Request fields but the app functions without them:
| Enabled API | Usage |
|---|---|
| Encounter.Read (Patient Chart) | Encounter context from launch |
| Encounter.Search (Patient Chart) | Active encounter lookup |
| Location.Read | Facility, department, room, bed |
| Observation.Search (Vital Signs) | Vital signs (height, weight) |
| Coverage.Search | Active insurance information |
| AllergyIntolerance.Search (Patient Chart) | Patient allergies |
| Condition.Search (Encounter Diagnosis) | Encounter diagnoses |
| Condition.Search (Health Concerns) | Health concerns |
| Condition.Search (Medical History) | Medical history |
| Condition.Search (Problems) | Problem list |
VectorCare setup
Before you configure your EHR, VectorCare staff will work with you to set up your organization. Contact us to begin.
What VectorCare provisions
- Organization — Your VectorCare organization, representing your health system.
- Services — The VectorCare services (e.g., Transport, Home Health, DME) enabled for your organization.
- Org ID — A unique identifier (e.g.,
abcd1234) that links your EHR launch to your VectorCare organization. You will include this value in your launch URL.
NOTE
VectorCare issues separate Org IDs for non-production and production environments.
What you provide to VectorCare
FHIR server base URL — The base URL of your FHIR R4 server. For example:
https://fhir.yourorganization.org/api/FHIR/R4
VectorCare staff will register this and associate it with your Org ID. During the SMART launch flow, our app will discover your EHR's authorization endpoints via /.well-known/smart-configuration.
OIDC issuer for ID Tokens — The iss claim value from the OpenID Connect ID Tokens issued by your EHR's authorization server. VectorCare uses this value to validate ID tokens during token exchange with VectorCare's own OAuth2 service. For example:
https://fhir.yourorganization.org/fhir/oauth2
NOTE
In many EHR configurations, the FHIR server base URL and the OIDC issuer are the same value.
Configuring your EHR
The following sections describe what your EHR IT team needs to configure. This is the core of the integration work.
Configure the EHR launch
VectorCare SMART on FHIR supports an EHR Launch flow. Your EHR initiates the launch by opening the app in an embedded browser or iframe and passing the appropriate SMART launch parameters. If your EHR requires an Integration Type setting, select "SMART on FHIR".
Client ID
The Client ID identifies the VectorCare SMART on FHIR application and is used during the authorization flow. Obtain this from the app listing or from your VectorCare representative.
Launch base URL
| Environment | URL |
|---|---|
| Non-production | https://fhir-uat.vectorcare.com/smart/launch?clientHostSource=%CLIENTHOSTSOURCE%&orgId=YOUR_ORG_ID |
| Production | https://fhir.vectorcare.com/smart/launch?clientHostSource=%CLIENTHOSTSOURCE%&orgId=YOUR_ORG_ID |
- Replace
YOUR_ORG_IDwith the Org ID provided by VectorCare staff. %CLIENTHOSTSOURCE%is a template variable. If supported by your EHR, it is replaced at launch time with your EHR's origin so that VectorCare can authorize iframe embedding.
Launch parameters
During launch, your EHR shall append standard SMART launch parameters to the launch base URL:
| Parameter | Description |
|---|---|
launch | A short-lived, opaque launch token provided by your EHR. |
iss | The value of your EHR's FHIR server base URL |
Patient vs. Encounter launch
The app can be launched from either a Patient Chart or an Encounter Chart. When launched from an encounter, location-specific attributes from that encounter are prioritized when pre-populating fields, rather than scanning for the relevant encounter from a list.
Adding the launch button
Work with your EHR's configuration team to place a launch button (or activity/link) in the appropriate area of your clinical workflow, such as the patient sidebar or panel. Consult your EHR's documentation for instructions on registering a SMART on FHIR app and configuring the launch action.
Confirm authentication
VectorCare SMART on FHIR authenticates as a Confidential Client using asymmetric key authentication (RFC 7523):
- The app signs a JWT client assertion with its private key.
- During the authorization code-to-token exchange, the app sends this assertion along with the
client_assertion_typeofurn:ietf:params:oauth:client-assertion-type:jwt-bearer. - Your EHR's authorization server validates the assertion by fetching the app's public key from:
| Environment | JWKS endpoint |
|---|---|
| Non-production | https://fhir-uat.vectorcare.com/.well-known/jwks.json |
| Production | https://fhir.vectorcare.com/.well-known/jwks.json |
Confirm that your EHR's authorization server can reach this endpoint and supports private_key_jwt validation.
Refresh token support
The app requests the online_access scope, which enables session renewal via refresh tokens. When the user's access token nears expiration, the app will automatically request a new token using the refresh token—keeping the session alive without interrupting the user's workflow.
Confirm that your EHR:
- Issues refresh tokens when the
online_accessscope is granted. - Accepts refresh token requests authenticated with the same JWT client assertion method.
Confirm network reachability
The app is served from VectorCare's infrastructure and makes requests to your FHIR server and to third-party services. Ensure the following domains are reachable from EHR workstations and any servers that participate in the SMART launch flow.
Required origins
| Origin | Purpose |
|---|---|
https://fhir.vectorcare.com | Production app |
https://fhir-uat.vectorcare.com | Non-production app |
https://*.apple-mapkit.com | Map rendering for location-based services |
https://fonts.gstatic.com | Web fonts |
Server-to-server
Your EHR's authorization server must be able to fetch the VectorCare public key from https://fhir.vectorcare.com/.well-known/jwks.json to validate client assertions during token exchange.
Readiness checklist
In summary, confirm the following before going live:
- Confirm prerequisites are met
- Ensure FHIR APIs are available
- FHIR server base URL and OIDC issuer have been shared with VectorCare
- Org ID(s) received from VectorCare (production and non-production if applicable)
- EHR launch is configured to the correct launch URL (non-production and/or production)
- Launch button is placed in the appropriate clinical workflow
- JWKS endpoint(s) (
/.well-known/jwks.json) are reachable from your authorization server - Refresh tokens are issued when access token is granted
- Required network domains are reachable from EHR workstations and servers
Need help?
If you have questions or need assistance at any step, contact us or reach out to your VectorCare Community representative.