CharmHealth
Practice management EHR. ConnectHealth supports two independent CharmHealth flows: a proprietary OAuth 2.0 implicit-grant member SSO login (verified working end-to-end against a real CharmHealth account), and the standard SMART on FHIR authorization_code/client_credentials flow (generic plumbing wired the same way as every other EHR here; CharmHealth-specific endpoint/field details have not been confirmed yet).
Overview
ConnectHealth's CharmHealth integration supports two independent connection types, which you choose when creating the connection:
- SSO Login — CharmHealth's own proprietary OAuth 2.0 implicit-grant member sign-in. ConnectHealth builds and issues the login redirect to CharmHealth; the token is returned directly to your application's own callback URL, not to ConnectHealth. This flow has been tested end-to-end against a real CharmHealth account.
- Standalone / Embed / Backend — the standard SMART on FHIR OAuth flow (authorization_code for Standalone/Embed, client_credentials for Backend), wired through the same shared machinery every other EHR in ConnectHealth uses. This is generic, working code — but CharmHealth's exact authorize/token endpoint values, required scopes, and developer-portal registration steps have not been verified yet, so this flow is ready to be exercised as soon as those details are available.
You (your organization) must obtain your own CharmHealth SSO Client ID (and, for the standard flow, your own CharmHealth API credentials) directly from CharmHealth. ConnectHealth is middleware — it does not create CharmHealth applications or manage your CharmHealth developer account.
On This Page
Supported Authentication Flows
SSO Login (verified)
CharmHealth's proprietary OAuth 2.0 implicit-grant member sign-in. Best for letting a CharmHealth practice's members sign in to your application using their existing CharmHealth credentials.
Standalone OAuth
Standard OAuth 2.0 authorization code flow. Same generic shape as every other EHR in ConnectHealth — field values are entered per connection, nothing is pre-filled for CharmHealth yet.
Backend (Client Credentials)
Server-to-server authentication with no user interaction, using a Client ID + Client Secret. JWT-bearer assertion is not yet implemented for CharmHealth.
Embed Launch
SMART on FHIR launch flow for applications embedded within CharmHealth's interface.
Key Features
- Proprietary implicit-grant SSO login — verified end-to-end against a real CharmHealth account
- Standard OAuth 2.0 authorization_code / client_credentials flow (generic plumbing)
- Audit logging for all operations
Before You Begin
What you need depends on which flow you're configuring.
For SSO Login
- A CharmHealth SSO Client ID — issued by CharmHealth for your practice. Contact CharmHealth to obtain one.
- Your application's own callback URL — CharmHealth redirects the browser here directly with the token after sign-in (not to ConnectHealth). This exact URL must be registered with CharmHealth against your Client ID.
For Standalone / Embed / Backend
- CharmHealth API / developer credentials — the exact registration process (developer portal URL, required forms/agreements) has not been documented here yet. Contact CharmHealth directly to get set up.
- Your CharmHealth authorize/token endpoint URLs and required scopes — these are entered manually per connection; ConnectHealth does not have CharmHealth-specific defaults for this flow yet.
Configuration Reference
SSO Login (verified)
CharmHealth returns access_token/id_token directly in the redirect URL's fragment (response_type=token) to ConnectHealth's callback page, which verifies the id_token against CharmHealth's published signing keys and then sends the browser on to your Application Return URL. CharmHealth's own tokens are never forwarded to your application.
| Field | Autofill | Required | Description |
|---|---|---|---|
SSO Client ID | No | Yes | Issued by CharmHealth for your practice. |
Authorize Endpoint | No | Yes | CharmHealth's OAuth authorize endpoint for your practice, e.g. https://accounts.charmtracker.com/oauth/v2/auth. |
Scope | Suggested default | Yes | Defaults to openid email, editable. |
Response Type | Suggested default | Yes | Defaults to token (the implicit-grant value), editable. |
Redirect URI | Yes | Yes | ConnectHealth's callback page for this connection (/api/charmhealth/sso/{connectionId}/callback). Register this exact URL with CharmHealth. |
Application Return URL | No | No | Where the browser lands after sign-in, e.g. https://app.example.com/after-login. Without it, the user just sees "Signed in with CharmHealth". |
What happens after sign-in
Once the id_token verifies, the browser is sent to your Application Return URL with success=true, token_id and expires_in appended. token_id is an opaque handle, valid for 5 minutes. From your backend, call GET /api/charmhealth/sso/{connectionId}/result/{token_id} with your x-api-key to get the member's sub and email. The member's identity is never put in the URL.
Standalone OAuth
Standard OAuth 2.0 authorization code flow. This uses the exact same generic implementation every other EHR here uses — no CharmHealth-specific field defaults or quirks are baked in yet.
| Field | Autofill | Required | Description |
|---|---|---|---|
Client ID | No | Yes | From your CharmHealth API application. |
Client Secret | No | No | Only if your CharmHealth application is a confidential client. |
Authorization URL | No | Yes | CharmHealth's OAuth authorize endpoint — enter the exact value CharmHealth gives you. |
Token URL | No | Yes | CharmHealth's OAuth token endpoint. |
Scopes | No | Yes | Space-separated scopes CharmHealth requires for this workflow. |
Redirect URL | Yes | Yes | Your ConnectHealth OAuth callback URL — register this exact value with CharmHealth. |
Base URL | No | Yes | CharmHealth's FHIR/API base URL for this connection. |
Backend (Client Credentials)
Server-to-server authentication with no user interaction. Only Client Secret (Basic Auth) is implemented today — JWT-bearer assertion is not yet supported for CharmHealth, since its exact requirements aren't confirmed. Configuring a JWKS key pair instead of a Client Secret will fail with a clear "not implemented" error rather than attempting unverified signing.
| Field | Autofill | Required | Description |
|---|---|---|---|
Client ID | No | Yes | From your CharmHealth API application. |
Client Secret | No | Yes | Used for HTTP Basic Auth against the token endpoint. |
Token URL | No | Yes | CharmHealth's OAuth token endpoint. |
Base URL | No | Yes | CharmHealth's FHIR/API base URL. |
Scopes | No | No | Space-separated system-level scopes, if CharmHealth requires them. |
Embed Launch
SMART on FHIR launch flow for applications embedded within CharmHealth's interface. Generic implementation — CharmHealth-specific launch behavior has not been verified.
| Field | Autofill | Required | Description |
|---|---|---|---|
Client ID | No | Yes | From your CharmHealth API application. |
Client Secret | No | No | Only for confidential clients. |
Get Your ConnectHealth API Key
Several ConnectHealth endpoints for the Standalone/Backend/Embed flows require a ConnectHealth API key passed as the x-api-key header. Without it, these endpoints return 401 Unauthorized. The SSO Login flow's endpoints are public and do not need an API key.
Log in to the ConnectHealth Dashboard
Open your ConnectHealth instance and sign in with your account credentials.
Navigate to Settings → API Keys
From the left navigation, click Settings, then open the API Keys tab.
Create a Key and Use It in the x-api-key Header
Click Create API Key, name it, and pass it on every protected request:
curl -X GET "https://<your-ch-domain>/api/workflow/auth/{integrationId}/token/exchange/{tokenId}" \
-H "x-api-key: YOUR_API_KEY" \
-H "Accept: application/json"API Endpoints
SSO Login
| Method | Endpoint | Description |
|---|---|---|
GET |
/api/charmhealth/sso/{connectionId}/start |
Redirects the browser to CharmHealth's real sign-in page, built from this connection's Client ID/Scope/Response Type/Redirect URI. This is the "Launch URL" shown on the connection page and the button used on the Test Connection page. |
GET |
/api/charmhealth/sso/{connectionId}/callback |
Public. CharmHealth redirects here after sign-in; the page reads the token from the URL fragment and posts it to /complete. |
POST |
/api/charmhealth/sso/{connectionId}/complete |
Public, called by the callback page. Verifies the id_token and returns your Application Return URL with a token_id. |
GET |
/api/charmhealth/sso/{connectionId}/result/{token_id} |
Requires x-api-key. Redeems token_id for { sub, email }. |
Standalone / Embed / Backend (shared with every other EHR)
Same generic endpoints as every other EHR integration in ConnectHealth, prefixed with /api/workflow/auth/{integrationId}.
| Method | Endpoint | Description | API Key |
|---|---|---|---|
GET | /api/workflow/auth/{integrationId}/start | Initiate the Standalone OAuth flow. | No |
GET | /api/workflow/auth/{integrationId}/callback | OAuth redirect URI — called by CharmHealth, not your client. | No |
GET | /api/workflow/auth/{integrationId}/token/exchange/{tokenId} | Exchange a one-time token ID for the actual access token. | Yes |
GET | /api/workflow/auth/{integrationId}/token | Request a Backend token via client_credentials. | Yes |
POST | /api/workflow/auth/{integrationId}/token/refresh | Refresh an expiring access token. | Yes |
GET | /api/workflow/auth/{integrationId}/introspect | Introspect the currently stored token. CharmHealth's real introspection endpoint is unknown, so this currently returns a 501 rather than falsely reporting the token as valid. | Yes |