# 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](https://one.healthsherpa.com/vibe-coders.html#prompt-for-builder) on the vibe-coders page after a quote prototype is built.

**Not legal advice.** Read the [Terms of Service](https://one.healthsherpa.com/legal/healthsherpa-one-api-terms-of-service.html) 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](https://one.healthsherpa.com/openapi.json)

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

| Environment | API base |
|---|---|
| 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](https://one.healthsherpa.com/docs/integration-guide/compliance-considerations.html).

## 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](https://one.healthsherpa.com/vibe-coders.html)
- [Onboarding](https://one.healthsherpa.com/docs/getting-started/onboarding.html)
- [Compliance considerations](https://one.healthsherpa.com/docs/integration-guide/compliance-considerations.html)
- [Terms of Service](https://one.healthsherpa.com/legal/healthsherpa-one-api-terms-of-service.html)