Carrier Credentials Setup

Levy Cover reads carrier credentials at runtime from environment variables. This page describes the credentials each carrier expects, where to set them, how to rotate them, and how to verify they are wired correctly.

Cover Genius (primary)

Two variables, both required:

COVER_GENIUS_API_KEY=<from Cover Genius portal>
COVER_GENIUS_PARTNER_ID=<from Cover Genius portal>

• COVER_GENIUS_API_KEY authenticates every API call. Bearer-style.
• COVER_GENIUS_PARTNER_ID identifies Levy Fleets to Cover Genius and is used to route quotes to the correct distributor contract.

Both values come from the Cover Genius partner portal. Sandbox and production have separate keys; never share keys across environments.

If either variable is missing, CoverGeniusClient throws CarrierNotConfiguredError. In dev and test, the registry falls back to the mock carrier. In production, quotes return available: false and the opt-in card is hidden.

Slice (Phase 2 fallback)

Slice ships in Phase 2 as a fallback carrier for jurisdictions Cover Genius cannot cover. When enabled, set:

SLICE_API_KEY=<from Slice partner portal>
SLICE_PARTNER_ID=<from Slice partner portal>

The shape of the variables matches Cover Genius. The jurisdiction matrix routes the right carrier per region (see Jurisdiction Matrix).

Mock carrier (development and tests)

The mock carrier requires no credentials. It is selected automatically when NODE_ENV !== 'production' and the real carrier credentials are absent. It generates synthetic policy IDs and claim IDs so the full code path can be exercised without hitting a real carrier.

Tests can pin the registry to the mock client using setCarrierRegistryForTests, which is documented in the test helpers under src/lib/insurance/__tests__/.

Vercel environment scoping

Set credentials under Vercel Project Settings > Environment Variables:

A redeploy is required the first time you set the variables. After that, rotating values takes effect on the next invocation (Vercel reads env vars per request).

Webhook secret

The Cover Genius webhook signature secret is a separate variable:

COVER_GENIUS_WEBHOOK_SECRET=<from Cover Genius portal>

The webhook router uses this to verify the HMAC signature on every inbound event. If the secret is missing, signature verification fails, and events land in insurance_webhook_log with signature_verified = false. Set this per environment alongside the API key.

Rotation

Cover Genius supports key rotation through the partner portal. The rotation procedure:

1. Generate a new key in the Cover Genius portal.
2. Set the new value in Vercel for the appropriate environment.
3. Trigger a redeploy (or wait for the next deploy - changes take effect at the next cold start).
4. Confirm a fresh quote succeeds.
5. Revoke the old key in the Cover Genius portal.

Do not revoke the old key before the new key is verified. Cover Genius does not pre-stage future credentials; the only safe order is set-new -> verify -> revoke-old.

Verification

After setting credentials, verify the wiring:

1. From an authenticated session on the dashboard, hit /api/admin/insurance/carriers. It should list cover_genius with configured: true.
2. Trigger a sandbox unlock and inspect the response from /api/mobile/insurance/cover/quote. A correctly configured carrier returns at least one tier with a non-zero premium.
3. Inspect Vercel logs for CarrierNotConfiguredError. Any occurrence indicates a misconfigured environment.

What never goes in env vars

• Per-subaccount commission percentages. These live in insurance_offerings and are operator-editable.
• Tier prices. Prices are carrier-determined and returned by the quote endpoint per ride.
• Rider PII. PII is shared with the carrier per binding via the API, not stored in env.

The global commission tunables INSURANCE_LEVY_GROSS_PCT (default 25) and INSURANCE_OPERATOR_SHARE_PCT (default 50) are environment variables, but they are commission policy values, not secrets - rotation rules do not apply.

---