iFrame and Embedded Integrations in Healthie

Healthie supports multiple ways to embed external content and applications directly within the provider UI. Whether you are a customer looking to surface a third-party tool inside a client profile, or a partner building a deeper integration, Healthie offers a range of iFrame and widget options to fit your needs.

This guide can be used by Enterprise customers and integration partners embedding external applications within the Healthie platform.

iFrame and embedded integration features are available to Healthie Enterprise customers with a full white-label. Contact your Customer Success Manager or hello@gethealthie.com to confirm eligibility.

Healthie iFrame Types 

Healthie supports three distinct integration patterns. The right choice depends on whether you need to surface UI inside Healthie, whether the content involves sensitive data, and whether your application needs to call the Healthie API on behalf of a logged-in provider.

Choosing the Right Approach

Here's a quick and easy guide on how to choose the right approach for your workflow and needs:

• You do not need to show UI inside Healthie 👉 API Only
• You need to show UI and the content is not sensitive or identity-dependent 👉 Standard iFrame
• You need to show UI and your app requires verified provider identity, patient context, or Healthie API access 👉 Authenticated iFrame

Where iFrames Can Appear in Healthie

Healthie supports iFrame embedding in multiple areas of the provider interface. Each location has its own setup process and eligibility requirements.

Client Profile Tabs

Custom tabs can be added inline alongside the default tabs on a client profile (Overview, Care Plans, Journal, and others). When a provider clicks a custom tab, the main content area is replaced with an iFrame that loads your content at full width. The iFrame URL receives the patient's Healthie ID and the current user ID as URL parameters.

This is the primary surface for partner integrations and supports both the Standard and Authenticated iFrame patterns.

Client Overview and Quick Profile

iFrames can be embedded within the Client Overview page and the Quick Profile view, appearing as configurable components alongside other content. These are configured by the Healthie team and activated by the org owner in Settings. They are org-wide and affect all providers and all client profiles in that organization.

Learn more 

Forms (Form Builder)

External content can be embedded directly inside a Healthie form using the Embed External Website question type. This works in intake forms, charting templates, and Programs.

Supply the URL in the following format:

https://your-app.com?width=100&width_type=percent&height=100&height_type=vh   

Width and height are controlled via URL parameters. Supported units are percent, vh, and px. Healthie generates the iFrame HTML automatically, you supply only the URL. The form iFrame module passes the client's Healthie User ID and the parent URL.

Learn more

Programs

iFrames can be added to Programs built within Healthie, useful for embedding third-party exercises, assessments, or supplemental content within a care program.

Other Locations

Have a use case that doesn't fit the locations above? 

Reach out to hello@gethealthie.com and we'll work with you to find the right solution.

Standard iFrame: URL Parameter Identification

For integrations that do not require authenticated API access, Healthie passes context via URL parameters when loading your iFrame.

Parameters Passed by Healthie

hl_current_user_id: Healthie appends this query parameter to your iFrame URL with the Healthie user ID of the logged-in provider. Your application can read this value from the URL to identify which user is accessing the integration.

referrer_url: Healthie also passes a referrer_url parameter containing the full URL of the page the provider was viewing when the iFrame loaded.

For iFrames embedded on a patient profile or client tab, the patient's Healthie ID appears in the path of this URL in the format:

/users/<patient_id>/...

Example URL your iFrame might receive:

https://your-app.com/healthie-embed
  ?hl_current_user_id=1015510
  &referrer_url=https%3A%2F%2Fsecurestaging.gethealthie.com%2Fusers%2F98765%2Foverview

Extracting the Patient ID

To extract the patient ID from referrer_url, parse the path segment:

javascript
const params    = new URLSearchParams(window.location.search);
const referrer  = params.get('referrer_url');
const patientId = referrer?.match(/\/users\/(\d+)/)?.[1];  // e.g. '98765'

⚠️ Important: URL parameters are not cryptographically signed. They are appropriate for identifying context in low-risk, non-PHI use cases. For any integration that calls the Healthie API or accesses sensitive patient data, use the Authenticated iFrame JWT flow instead.

Authenticated iFrames: Secure Partner Integrations

The Authenticated iFrame integration allows partner applications to be embedded directly inside the Healthie provider UI as a custom tab, with a secure, short-lived JWT automatically passed to the partner application in the background. The logged-in provider is instantly recognized in the partner app with no separate login required.

This is the recommended approach for any integration that involves PHI, requires verified provider identity, or needs to call the Healthie API on behalf of a logged-in user.

How It Works

The token is never exposed in a URL, browser history, or server logs. It is delivered exclusively through a secure browser channel that only your embedded application can receive.

Tokens are valid for 15 minutes and are automatically refreshed by Healthie approximately 60 seconds before expiry. Under normal conditions, a session will never drop due to token expiration.

Receiving a Token

Listen for messages from the Healthie parent frame. The expected origin depends on the environment:

javascript
const HEALTHIE_ORIGIN = 'https://secure.gethealthie.com'
// staging: 'https://securestaging.gethealthie.com'

window.addEventListener('message', (event) => {
  if (event.origin !== HEALTHIE_ORIGIN) return
  if (event.data?.type === 'HEALTHIE_JWT_TOKEN') {
    const { token, silent } = event.data
    // Store the token and use it for API requests
    // silent=true means this is a background refresh — avoid re-triggering loading states
  }
})

JWT Claims

All tokens include the following standard claims:

Optional Claims

Additional claims can be included in the JWT if your app has been configured with the corresponding allowed_claims. Contact Healthie to request access to any of the following:

Reading Claims from the Token

When patient_id is configured, it is cryptographically bound to the token, the claim cannot be forged or tampered with independently of the token signature. To read claims from the token, decode it with a JWT library such as jwt-decode :

javascript
import { jwtDecode } from 'jwt-decode'

window.addEventListener('message', (event) => {
  if (event.origin !== HEALTHIE_ORIGIN) return
  if (event.data?.type !== 'HEALTHIE_JWT_TOKEN') return
  const claims = jwtDecode(event.data.token)
  const patientId = claims.patient_id // present only if configured
})

Making API Requests

Include the JWT in the Authorization header of your GraphQL requests:

https
POST https://api.gethealthie.com/graphql
Authorization: Bearer <token>
AuthorizationSource: ThirdPartyApp
Content-Type: application/json

Token Refresh

Healthie manages token refresh in two ways:

• Proactive refresh: Healthie automatically sends a new token approximately 60 seconds before the current one expires. You will receive another HEALTHIE_JWT_TOKEN  message with silent: true. Replace the stored token and continue without re-triggering loading states in your UI.
• On-demand refresh: If your app detects a 401 error from the Healthie API, post a TOKEN_EXPIRED  message back to Healthie. A fresh token will be issued within seconds.

javascript
window.parent.postMessage({ type: 'TOKEN_EXPIRED' }, HEALTHIE_ORIGIN)

Healthie Widgets

In addition to embedding external applications via iFrame, Healthie also supports embedding Healthie's own native UI components as widgets. This allows customers and partners to surface Healthie's product functionality, such as charting, scheduling, or intake form components, directly within their own platform or within specific areas of the Healthie interface.

Unlike iFrames that embed your application inside Healthie, Healthie Widgets surface Healthie's own UI within another context. This approach is used when the goal is to expose Healthie functionality rather than bring in an external tool.

Contact your Healthie Customer Success Manager to discuss which widget components are available and how they can be incorporated into your integration.

Security Requirements and Best Practices

Healthie takes the security of iFrame integrations seriously. Because iFrames load external resources within the Healthie interface, all partner and customer URLs are subject to review and approval by the Healthie team before being configured. Org owners cannot independently set arbitrary iFrame URLs.

Requirements for iFrame URLs

• All iFrame URLs must use HTTPS.
• URLs must be reviewed and configured by the Healthie team.
• Embedded resources should not load third-party scripts or assets from unreviewed CDNs without Healthie approval.
• Servers hosting iFramed content should be kept up to date. A recent penetration test (preferably third-party) may be requested.
• URLs should not contain PHI such as a patient's name in plaintext.
• If the URL changes after initial setup, customers must submit a new request for review and update.

Common Issues

• CORS errors: The server hosting the iFrame content must permit cross-origin requests from the Healthie domain.
• X-Frame-Options blocking: If your server sends an X-Frame-Options: DENY or SAMEORIGIN header, Healthie cannot load the iFrame. Configure your server to allow framing from the Healthie domain.
• Expired tokens (Authenticated iFrame): Under normal conditions tokens refresh automatically. If a 401 is returned, send a TOKEN_EXPIREDpostMessage to request a new token.
• Authentication not shared (Standard iFrame): For standard iFrames, authentication is not shared between the Healthie parent window and the iFrame. If your app requires login, providers will need to authenticate separately.

Getting Started

For Customers

Contact your Customer Success Manager or email hello@gethealthie.com

• iFrame support in Client Profile Tabs, Client Overview, or Quick Profile. Be prepared to provide the URL, a display label, and your preferred location.
• Healthie will configure the iFrame in your staging environment so you can verify behavior before production rollout.

For Partners (Authenticated iFrame)

Contact your Healthie partnerships contact to begin onboarding. You will need to provide:

• Your staging application URL
• Your production application URL
• Let us know if you need any additional parameters (e.g. patient_id) and we can review on a case-by-case basis.
• The label you would like displayed on the tab in the Healthie UI

Healthie will configure the integration on a test account and share access so your team can begin building and testing before production rollout.

Frequently Asked Questions

Does Healthie pass a client's email or other personal information into the iFrame automatically?

No. Healthie does not directly pass client email addresses or other PII in URL parameters. For Form iFrames, Healthie passes the client's Healthie User ID and the parent URL. You can use the Healthie API to look up additional client information as needed.

Can the patient_id JWT claim be forged or spoofed?

No. When patient_id is included in the JWT, it is cryptographically bound to the token signature using AWS KMS. Modifying any claim, including patient_id, invalidates the signature, and the Healthie API will reject the request.

Is authentication shared between the Healthie parent window and a standard iFrame?

No. For standard iFrames, authentication is not shared. If your embedded app requires a login, providers would need to sign in separately. The Authenticated iFrame pattern eliminates this by automatically passing a secure token to your app.

Are iFrame configurations specific to individual patients?

No. iFrame configurations are org-wide. They appear consistently across all client profiles in the organization. If you want to vary the content shown for different patients, that logic should be handled within your embedded application.

What happens if the JWT token expires during an active session?

Under normal conditions, tokens will not expire during an active session. Healthie proactively refreshes them 60 seconds before expiry. If your app does receive a 401 from the Healthie API, post a TOKEN_EXPIRED message to the Healthie parent frame and a fresh token will be issued within seconds.

Is the Authenticated iFrame different from Healthie's SSO offering?

Yes. Healthie's SSO feature allows providers to use an external identity provider (such as Okta or Azure AD) to log in to Healthie. Authenticated iFrames solve a different problem: they allow a partner application embedded inside Healthie to automatically recognize the already-logged-in provider, eliminating a second login to the partner app. The two features are complementary but distinct.

Is this available to all Healthie customers?

iFrame support in its various forms is available to Healthie Enterprise customers with full web white-label add-on. Authenticated iFrames also require a full white-label and a minimum contract size. Contact your Healthie partnerships or customer success contact to confirm eligibility.