ChartHero Developer Docs
API ReferenceOpenAPI JSON
Get Started

Core Concepts

AuthenticationScopesPagination

Guides

Fetch encountersFetch documentsFetch transcript and audioReceive webhooksVerify webhook signatures
API ReferenceWebhooksErrorsChangelog

Core concept

Authentication

API key headers, safe key handling, access checks, and common authentication errors.

API key header

Every public API request must include an API key in the Authorization header as a bearer token.

HTTP
Authorization: Bearer ch_sk_example_123

Send the header from your server-side integration. Do not send API keys in query parameters.

Keep keys secret

API key values are shown only as synthetic placeholders in these docs. Treat production API keys as secrets.

Store keys in a server-side secret manager or encrypted configuration. Do not place keys in browser code, mobile applications, logs, analytics events, customer-visible error messages, or support screenshots. Rotate a key if it may have been exposed.

Access checks

ChartHero checks API-key validity, partner route enablement, and required scopes before returning data or parsing route-specific query parameters.

A request may be denied when:

  1. The API key is missing or invalid.
  2. The key is inactive, expired, or revoked.
  3. The key does not include the required scope.
  4. The key is not scoped to a partner organization.
  5. The requested resource is outside the caller's organization.
  6. The route has not been enabled for the partner.

Because route-level checks run first, a request that fails authentication, partner enablement, or scope checks can return an authentication or authorization error even if the URL also contains an invalid query parameter. After those checks pass, unsupported query parameters can be reported before ChartHero looks up a specific resource.

Production access

Production API access is enabled per partner organization and route. Before sending production traffic, confirm that ChartHero has enabled the routes your integration needs and issued a production API key with the required scopes.

Use separate keys for separate environments when they are provided. A test key may be rejected in production, and a production key should not be used in local development or shared test tooling.

Common authentication errors

HTTP status reason_code What it means What to do
401 missing_bearer The request did not include a bearer API key. Send Authorization: Bearer <api_key>.
401 malformed_token or invalid_key The API key could not be read or is not recognized. Check that you are using the full key for the correct environment.
401 disabled_key, expired_key, or revoked_key The key is no longer active. Replace the key with an active one.
401 api_keys_disabled or test_prefix_not_allowed API-key access is not available for this request or environment. Confirm the environment and key type with ChartHero.
403 org_scope_only_required The route requires an organization-scoped API key. Use an organization-scoped key issued for the partner organization.
403 missing_scope The key does not include every scope required by the route. Request the smallest additional scope set needed for the integration.
403 route_not_allowed or organization_not_allowlisted The route has not been enabled for the partner organization. Ask ChartHero to enable the route before retrying.
403 cross_organization_denied or demo_training_denied The resource is not available to this integration. Treat the resource as unavailable through the public API.

Next steps

Review Scopes for route-level requirements and Errors for the standard error body and client handling guidance.

Next steps

Review required scopes

Map routes to the minimum bearer-token scopes.