Hint Health Authentication

generated: '2026-08-15'
method: searched
source: https://developers.hint.com/reference/making-requests
docs: https://developers.hint.com/reference/making-requests
name: Hint Health Authentication
description: 'Hint is a single-mechanism API: a bearer token in the Authorization header, on every operation, with no OAuth
  scopes and no OIDC. What varies is WHICH token, and getting that wrong is the highest-consequence mistake on this API —
  the partner key and the practice access token address different surfaces, and using the partner key against /api/provider/*
  crosses practice boundaries.'
summary:
  types:
  - http
  - apiKey
  api_key_in:
  - header
  oauth2_flows: []
  scopes_published: false
  openid_connect: false
  mtls: false
schemes:
- name: BearerAuth
  type: http
  scheme: bearer
  header: 'Authorization: Bearer <token>'
  standard: RFC 6750
  description: The form documented on "Making Requests" and applied to every operation in the 49 refined specs in openapi/.
  sources:
  - openapi/*.yml
- name: hint_api_key
  type: apiKey
  in: header
  parameter: AUTHORIZATION
  description: The scheme Hint's OWN published OpenAPI declares — an apiKey in the AUTHORIZATION header whose description
    instructs callers to send "Bearer {your_api_key}". Functionally identical to the above; recorded separately because it
    is what the provider's document actually says.
  sources:
  - openapi/_original/hint-health-partner-endpoints-2026-07-01-openapi.yml
  note: 'A tooling nit with a real cost: declaring RFC 6750 bearer auth as an apiKey scheme means generated clients and gateways
    will not recognise it as bearer auth, and no `bearerFormat` is advertised.'
token_types:
- name: Practice access token
  surface: /api/provider/*
  scope: one practice
  issued_by: POST /api/partner/installations/connect (or the older POST /oauth/tokens), exchanging the authorization code
    Hint hands over at install time. The credential is returned in api_keys[0].token.
  lifetime: No expiry is published — Hint's own connect example returns expires_in null and refresh_token null. Treat the
    token as long-lived and rotate it through the installation API keys endpoints rather than by refresh.
  guidance: This is the ONLY token that may touch practice data. Hint states plainly that using the partner key here leaks
    across practices.
- name: Partner API key
  surface: /api/partner/*
  scope: the whole partner account
  issued_by: The Hint Partner Portal, and manageable via /partner/api_keys.
  env_var: HINT_API_KEY
  guidance: Marketplace, product listing, installation, backend and webhook-endpoint administration only.
environments:
  selector: key prefix, not host
  detail: A key prefixed `sbx-` returns sandbox data; an unprefixed key returns live data. api.hint.com serves BOTH, so promoting
    an integration from sandbox to live requires no host change. Partner identifiers carry the same prefix — ptr-... live,
    sbx-ptr-... sandbox.
  hosts:
  - name: production
    url: https://api.hint.com
    key_prefix: none
  - name: sandbox
    url: https://api.sandbox.hint.com
    key_prefix: sbx-
  - name: staging
    url: https://api.staging.hint.com
    key_prefix: sbx-
authorization_model:
  scopes: none
  detail: There is no scope parameter, no scope registry and no per-endpoint permission grant. Authorization is entirely a
    function of which token family you hold and which practice it was issued for. derive-oauth-scopes.py finds 0 oauth2 schemes
    and 0 scopes across all 49 specs, so no scopes/ artifact is emitted.
  roles:
    docs: https://developers.hint.com/docs/roles-and-access-context
    detail: Roles apply to USERS inside an embedded marketplace app, not to API tokens. Hint passes a partner role and an
      access_context on the app handshake, and apps are expected to handle Hint platform-support sessions differently — a
      user-level authorization signal that has no API-token equivalent.
webhook_authentication:
  direction: hint-to-partner
  mechanism: HMAC-SHA256 signature
  header: X-Hint-Signature
  format: sha256=<hmac>
  signed: raw request body
  key_source: Partner Portal → Webhooks Signature Key (HINT_WEBHOOK_SECRET on hosted deploys)
  see_also: asyncapi/hint-health-webhooks.yml
embedded_app_authentication:
  mechanism: signed handshake + server-minted session key
  detail: Marketplace apps receive a signed payload at POST /hint/handshake (same X-Hint-Signature HMAC), verify it, mint
    their own session key, and use it on subsequent surface renders. The Hint API token is never exposed to the browser.
  see_also: components/hint-health-components.yml
discovery:
  well_known: none
  detail: No /.well-known/openid-configuration, /.well-known/oauth-authorization-server or /.well-known/oauth-protected-resource
    is served on any Hint host — all 404. An agent cannot discover how to authenticate; it must read the docs.
  see_also: well-known/hint-health-well-known.yml
gaps:
- No token expiry, refresh flow or rotation policy is documented.
- No scopes, so an integration that needs read-only access cannot be granted it.
- Bearer auth is declared as an apiKey scheme in the provider's own OpenAPI, so the machine-readable contract understates
  the auth model.
docs_all:
- https://developers.hint.com/reference/making-requests
- https://developers.hint.com/docs/setting-up-your-sandbox-account-api-keys
- https://developers.hint.com/docs/integration-activation
- https://developers.hint.com/docs/roles-and-access-context