HIPAA Configuration Guide: Setting Up Ethora for PHI

Require two-step verification for administrators and owners

Switch it on for every app that will hold PHI. Administrators who have not set up an authenticator are sent to Account › Security after their next sign-in and cannot use the admin panel until they do. End users of your app and API clients are not affected; their second factor is your decision in your own identity system.

Why: an administrator account can read every room, export history and change every setting below. The Security Rule's access control and person authentication standards (45 CFR 164.312(a) and (d)) are met for that account with a second factor.

Turn off self-registration and provision users yourself

Disable open registration so nobody can create an account in a PHI app by finding its sign-in page. Create patients, members and staff from the Users page, or from your own system through the API (one at a time or through the batch endpoint) so that identity stays in the system you already audit. Limit the sign-on options shown to the ones you actually use.

• Give collaborators on the app the narrowest role that fits; the owner role is for one or two people.
• Archive users who leave; an archived user cannot sign in or get a token, and their history stays in the archive.
• Keep the App Secret and server tokens in your secrets manager, label each token by the system that uses it, and revoke the ones you no longer use (Admin panel › API tab).

Why: HIPAA's minimum necessary rule and the workforce clearance and termination procedures (164.308(a)(3)) assume you decide who is in the system. Open registration gives that decision away.

Set push notifications to generic content

A chat push normally carries the sender's name and the message text, and that text passes through Google's and Apple's push servers, which are not under a BAA. In generic mode the notification says "New message" or "You have received N new messages" with no sender, no preview and no picture, while the badge, sound and the tap target still work. Set it once on your base app and every child app inherits it; GET on the same endpoint shows the mode in effect and where it comes from.

• If you ship your own React Native app, you can keep full content and use encrypted push notifications instead: the device key encrypts the push and the app decrypts it locally, so Apple and Google relay ciphertext.
• Sender avatars in pushes can be switched off separately (PUT /v1/push/sender-avatar/:appId); generic mode sends none either way.

Why: a message preview on a lock screen is a disclosure to whoever is holding the phone, and the push relay is a third party that would otherwise need its own BAA.

Confirm encryption in transit and at rest, and decide on encrypted rooms

On a dedicated server or Ethora Cloud, TLS 1.2+ on every endpoint and AES-256 at rest for the database, file storage and backups are part of the service. On a self-hosted server, the installer sets up TLS for the API, the chat server and file storage; you provide encrypted volumes for the database, server-side encryption on the file bucket, and encrypted backups, which every major cloud offers as a checkbox.

End-to-end encrypted rooms are an option per app, off by default. Leave them off unless you have a reason: in an encrypted room the server holds only ciphertext, so there is no server-side archive, search, export or moderation, and a records request or an audit cannot be answered from the server. Switch them on when a specific use needs it (for example a clinician-to-clinician channel where the organisation has agreed that no server copy exists) and document the decision.

Why: the Security Rule asks for encryption as an addressable safeguard (164.312(a)(2)(iv) and (e)(2)(ii)); it does not ask for end-to-end encryption, and most covered entities need the server-side record more than they need the server to be blind.

Switch on the immutable audit log export and set your retention

Ethora logs sign-ins, API calls, administrative actions and message events. The immutable export job copies new log entries on a schedule to an S3-compatible bucket you name; with object lock on the bucket, nobody, including an administrator, can alter or delete an exported window before its retention period ends. On a dedicated server or a HIPAA-enabled cloud account, support switches this on for you and confirms the bucket and the retention period in writing.

• Message history is kept until you delete it. Decide a retention period for messages and files (many organisations apply the six years HIPAA requires for policy documentation to the messages too), write it down, and delete per chat through the API when it ends.
• Export before you delete: chat history, users and files are available through the API, the admin panel and the Ethora MCP server, which is how you answer an access request under 164.524.

Why: audit controls (164.312(b)) and the documentation retention requirement (164.316(b)(2)) need a record that survives both time and a compromised administrator account.

Keep AI agents, retrieval and translation off for PHI, or bring a covered model

On Ethora Cloud, AI agents, retrieval over uploaded content and message translation run through a cloud model provider under Ethora's own key, with no BAA. Do not point an agent at rooms, documents or websites that contain PHI there, and leave message translation off for PHI apps. A public website assistant that answers general questions stays fine.

• On a self-hosted or dedicated server, each agent can use a model you host yourself through an OpenAI-compatible endpoint (Ollama, vLLM, LM Studio) so PHI never leaves your environment, or a cloud provider with which you have your own business associate agreement, using your key.
• Translation sends the message text to the translation provider for every configured language. Use it for PHI only with a provider covered by your own BAA, and only on a server where the provider is configured by you.
• A HIPAA-enabled cloud account has these features kept off by support until you confirm a covered model.

Why: every company that receives PHI on your behalf is a business associate and needs a BAA (164.502(e)); a model provider is no exception. The HIPAA compliant chatbot page has the full pattern.

Point webhooks and integrations only at systems under your control or your BAA

Webhook events carry message content, so every endpoint you register must be HTTPS, must belong to you or to a vendor with a BAA in place, and should verify the signature on each delivery. The same applies to anything that reads history through the API or the MCP server: a CRM, a helpdesk, an EHR bridge or a staff member's AI assistant connected over MCP is another client of the PHI and sits under your policies.

• Use one server token per integration, scoped to the app it serves, so a revoked token stops exactly one system.
• Account emails from Ethora (verification, sign-in, reports) carry no message content, so your email provider is not in the PHI chain.

Why: a webhook is a disclosure to whoever receives it. If that receiver has no BAA with you, the disclosure is not permitted.

Keep public widgets PHI-free, or embed them behind your login

A chat widget on a public website creates a visitor account per visit and anyone can type into it. Use it for conversations that do not involve PHI: hours, services, insurance accepted, how to book. Put a line in the greeting such as "Please do not share health information here; for anything about your care, sign in to the portal or call us", and route people there. If the widget must handle PHI, embed it inside your authenticated portal so only signed-in patients reach it, on a covered deployment.

Why: a public widget cannot verify who is typing, and PHI typed into it is PHI you now hold, with all the obligations that follow.

Treat the admin panel as a configuration surface and keep PHI out of support tickets

A self-hosted admin panel sends no product analytics to Ethora: tracking only runs on Ethora's own domains. On Ethora Cloud, the admin panel normally reports anonymous usage to product analytics tools; when HIPAA is enabled on your account, Ethora turns that off for your workspace, so a screen that shows a conversation is not captured. On your side, use demo data when you test with support, do not paste real messages into tickets or emails, and keep PHI in the app clients and the API rather than in the admin panel's own chat screens where you can.

Why: a session recording of an admin reading a patient's message is a copy of PHI in a tool that has no BAA. Removing the tool is simpler than covering it.

Cover the people and the devices around the workspace

Ethora runs on phones and laptops you do not control. Require a screen lock and remote wipe on any device that has the app with PHI; train staff on what belongs in a chat and what belongs in the record; apply the minimum necessary rule to who is added to which room; and name the person who receives security notices from Ethora. Ethora reports incidents and breaches of unsecured PHI to that person in writing within 10 business days of discovery and cooperates with your investigation; notices to individuals and to HHS stay with you.

• Suspected incidents on your side: security@ethora.com, acknowledged within 3 business days.
• Support, configuration changes and the BAA itself: support@ethora.com.

Why: the administrative safeguards (164.308) are most of the Security Rule, and no software setting replaces them.