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
  - 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
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.