Security

HealthSherpa ONE Integration Security

Technical security expectations for HealthSherpa ONE integrations: quoting, on-exchange enrollment handoff, and policy-status readback.

This guide is for developers and vibe coders building on HealthSherpa ONE. Apply these rules directly when generating or reviewing integration code. Vibe coders can also use the security prompt for quoting on the vibe-coders page after a prototype is built.

Not legal advice. Read the Terms of Service before production use with real consumers.

Scope

Covered here

  • Quoting (/v1/reference/*, /v1/quotes)
  • On-exchange handoff (/v1/enrollment-sessions)
  • Policy status (/v1/policy-status/*, alpha)

Not covered here

  • Off-exchange direct enrollment (/v1/enrollments) — see API docs and your HealthSherpa onboarding contact
  • Payment, bank accounts, PCI
  • Webhooks (HealthSherpa ONE public API has none)

Authoritative contract: OpenAPI specification.

API key and server-side proxy

Required pattern: browser → your backend → api.one.healthsherpa.com

  • Store the key in HEALTHSHERPA_API_KEY (or HS_API_KEY) in server secrets only
  • Send x-api-key from the server — not Authorization: Bearer
  • Never paste the key into AI builder chat, frontend code, public env vars, git, or README examples
  • Rotate immediately in the developer portal if exposed
Production
https://api.one.healthsherpa.com
Staging
https://staging-api.one.healthsherpa.com

Staging uses the same x-api-key pattern. Generate separate keys in the portal.

Quoting

Endpoints: county, issuer, and provider lookup; POST /v1/quotes

  • PII in requests: ZIP, income, age/DOB, tobacco — treat as sensitive. Do not log full request or response bodies.
  • Strict JSON: Unknown fields anywhere in the body return 400 invalid_request. Match OpenAPI exactly.
  • County flow: Resolve ZIP to FIPS before quoting. If multiple counties return, the user must select one.
  • Testing: Use synthetic household data in staging.
  • Consumer-facing apps: If shoppers see plan cards or rankings, review Compliance considerations.

Enrollment sessions (on-exchange)

Endpoint: POST /v1/enrollment-sessions with context.exchange: on_exchange

Returns HealthSherpa-hosted browser links — does not create application records.

  • Approval required: On-exchange enrollment access in the portal. 403 forbidden means fix setup (OAuth link, approvals), not retry.
  • agent_assisted: Linked agent OAuth; plan_id is not allowed in the request.
  • self_service: D2C deeplink agent ID configured in the portal.
  • Redirect safety: Only redirect to links.shopping_url or links.client_apply_url after validating https:// and a healthsherpa.com host. Do not log full URLs.
  • Idempotency: Optional Idempotency-Key header. Stored 5xx responses replay for the same key for 24 hours. If you believe a 503 was transient, generate a fresh Idempotency-Key before retrying.

Policy status (alpha)

Endpoints:

  • GET /v1/policy-status/applications?exchange=on_exchange&plan_year=YYYY
  • GET /v1/policy-status/applications/{confirmation_id}?exchange=on_exchange&plan_year=YYYY
  • Alpha: Not all applications have status data; empty or partial fields are normal.
  • Sensitivity: Marketplace consumer data — stricter than quote inputs.
  • Scope: Visible to the OAuth-linked agent only. Do not build public cross-consumer search or marketing datasets.
  • Server-side only: Same proxy pattern as quoting. No client-side API key or long-term client cache.
  • Testing: Do not use real consumer policy-status records for dev/testing except to serve that consumer (per Terms of Service).
  • Portal: If you linked OAuth before policy status was enabled, use Re-link account on the API Access page.

Logging, errors, and transport

  • HTTPS only; never disable TLS certificate verification
  • Redact in logs: ZIP, income, age/DOB, names, confirmation IDs, policy balances, enrollment redirect URLs
  • Do not send HealthSherpa ONE payloads to session replay or public error trackers unredacted
  • Do not retry 4xx; on 429, honor the Retry-After header
  • Report suspected breaches to security@healthsherpa.com (see Terms of Service)

Pre-ship checklist

  • API key server-side only
  • Browser → backend → HealthSherpa ONE with x-api-key
  • No sensitive bodies in logs or analytics
  • County resolved before quote when needed
  • OpenAPI-strict request bodies
  • Enrollment redirects validated before browser navigation
  • Policy status server-side with minimal retention
  • CMS/compliance reviewed if consumers see plan UI
  • Terms of Service reviewed before production with real consumer data

Related resources

  • Vibe coding prompts
  • Onboarding
  • Compliance considerations
  • Terms of Service