Ribbon Health Authentication

generated: '2026-08-14'
method: searched
source: openapi/ribbon-health-h1-api-openapi.yml
docs: https://ribbon.readme.io/docs/authentication
revised: '2026-08-14'
summary:
  types:
  - http
  api_key_in: []
  oauth2_flows: []
schemes:
- name: BearerAuth
  type: http
  scheme: bearer
  sources:
  - openapi/ribbon-health-h1-api-openapi.yml
  docs: https://ribbon.readme.io/docs/authentication
  header: 'Authorization: Bearer {customer_token}'
  credential: single long-lived customer API key
  issuance: >-
    Keys are issued through a sales/demo engagement at https://h1.co/request-demo/ — there is no
    self-serve key generation, no developer signup, and no key-management endpoint in the API.
  rotation_documented: false
  test_credentials: false
  test_credentials_note: >-
    No sandbox, no test mode and no separate test key prefix are documented, which is why there is
    no sandbox/ artifact in this repo. The only mode-like distinction is entitlement: the spec's
    own 403 example is "Trial accounts do not have access to custom specialties", so trial
    accounts exist but share the same production host and key format.
  provider_guidance: >-
    "Make sure to keep this API Key secure. Do not share your API Key in publicly accessible
    areas, such as Github, client-side code, or internal communication tools."
oauth2: false
oauth2_note: >-
  No OAuth, no OIDC, no scopes. /.well-known/oauth-authorization-server,
  /.well-known/oauth-protected-resource and /.well-known/openid-configuration all return 404 on
  api.ribbonhealth.com (probed 2026-08-14). There is no scopes/ artifact for this provider because
  there is no scope surface to capture — authorization is expressed as account-level product
  entitlements (e.g. `doctors.can_price_transparency`) enforced with HTTP 403, not as token scopes.
observed:
  method: probed
  checked: '2026-08-14'
  failures:
  - status: 401
    code: not_authenticated
    trigger: no Authorization header
  - status: 401
    code: authentication_failed
    trigger: syntactically valid but invalid bearer token
  note: >-
    The API distinguishes "no credential" from "bad credential" with two different machine codes,
    which is better than most. Branch on error.code — the same code returns two different message
    strings depending on the path.
agent_notes: >-
  A single static bearer secret with no scoping, no expiry and no rotation endpoint means an agent
  granted this key holds the customer's entire H1 surface, including the PHI-bearing eligibility
  endpoint. There is no way to issue a read-only or module-limited credential from the API. Scope
  the key at the account level with H1 before delegating it.
cross_links:
  conventions: conventions/ribbon-health-conventions.yml
  errors: errors/ribbon-health-problem-types.yml
  agentic_access: agentic-access/ribbon-health-agentic-access.yml