---
title: "Homeowners Operator Setup"
description: "One human setup flow to issue, store, and rotate operator keys before an agent ever uses the delegated homeowners loop."
canonical: "https://www.coveragecat.com/ai/skills/homeowners/setup"
last-updated: "2026-09-12"
---

# Homeowners Operator Setup

One human setup flow to issue, store, and rotate operator keys before an agent ever uses the delegated homeowners loop.

## Runtime links

- [Runtime skill page](/ai/skills/homeowners)
- [Skill markdown download](/api/agent/homeowners/skill.md)
- [OpenAPI spec](/api/agent/openapi.yaml)

## Get an operator key before you hand the runtime skill to an agent

This is a one-time human or integrator setup flow. Use an operator or integrator email here, never a customer's intake email. A single issued operator key can be reused across many delegated homeowners submissions for many different end-customer emails. Put the customer email only in intake.email, not in the OTP flow.

### How key scope works

- One operator key may submit quotes for many different customers. The key identifies your integration or operator, not the end customer.
- Coverage Cat keeps one active key per operator email. Re-running the OTP flow or rotating the key for that same email replaces the previous key immediately.
- If you want separate keys for production vs staging, or for distinct business units or tenants, use separate operator emails and complete this setup once per email.

### Where the key should live

- Store the issued key only in a server-side secret manager or deployment config.
- Never embed the key in browser code, mobile apps, customer-visible prompts, or CRM notes.
- Runtime agents should receive the current key out of band from your secret store and should never call the OTP endpoints during customer quoting.

## Guardrails

- Use the operator or integrator email for OTP request, OTP confirm, and key recovery. Never use a customer's intake email in the key flow.
- Store the issued operator key immediately in your secret manager or deployment config. Coverage Cat only shows the raw key once.
- Runtime agents should receive the current operator key out of band and should call only the public homeowners runtime contract endpoints.

## 1. Request a one-time code

Send an OTP request to the operator email you want tied to the key.
```sh
curl -X POST https://www.coveragecat.com/api/agent/key/request \
  -H "Content-Type: application/json" \
  -d '{"email":"you@yourco.com"}'
```

- Coverage Cat emails a 6-digit code to that address.
- Codes expire in 10 minutes.
- Requests are limited to 3 per hour per email.


## 2. Exchange the code for an operator key

Confirm the OTP with the operator email. Registration fields are optional but recommended for support and attribution. Use referral_source_name for the customer-facing partner or brand name that should appear in delegated-homeowners emails. Use assistant_email if delegated-umbrella customer emails should also be copied to your runtime assistant mailbox.
```sh
curl -X POST https://www.coveragecat.com/api/agent/key/confirm \
  -H "Content-Type: application/json" \
  -d '{
    "email":"you@yourco.com",
    "otp":"123456",
    "organization_name":"Acme",
    "referral_source_name":"Altgage Inc.",
    "contact_name":"Your Name",
    "assistant_email":"assistant@yourco.com",
    "use_case_description":"Homeowners referrals from Acme"
  }'
```

Response shape:

```json
{
  "status": "active",
  "api_key": "ccop_...",
  "key_prefix": "ccop_...",
  "expires_at": "...",
  "message": "Key issued. Save it now — it will not be shown again. Rotate via POST /api/agent/key/rotate."
}
```

- Save the key immediately. Coverage Cat only shows the raw key once.
- Confirmation attempts are limited to 5 per 10 minutes per email.
- For delegated umbrella follow-up, assistant_email is a CC-only mailbox for the same customer emails Coverage Cat sends during checkout. Your runtime agent should still poll the status endpoint.


## 3. Read the public contract

Both docs are unauthenticated. Use them to drive your runtime integration rather than hard-coding assumptions.
```sh
GET https://www.coveragecat.com/api/agent/homeowners/skill.md
GET https://www.coveragecat.com/api/agent/openapi.yaml
```


## 4. Run the delegated homeowners loop

Give the stored operator key to your runtime agent or service out of band. The same key can be reused across many customers; set each customer's real email on the intake as intake.email. Then call the homeowners quotes endpoint with Authorization: Bearer ccop_.... Omit uid on the first call, then reuse the returned uid on every follow-up. For a mocked rehearsal, set sandbox: true only on that first create call and use fake or test contact details; sandbox returns pending_quotes first, mocked offers on a later poll, and sends no live customer emails or carrier traffic. In live mode, fill missing_fields from your CRM or source systems first. When the only remaining missing field is credit_check_authorized, render a single review step to the real homeowner, explain that this is a soft credit pull with no credit-score impact, and only then resend the same uid with credit_check_authorized: true. Once the intake is submitted and status becomes pending_quotes, Coverage Cat will also send system emails to that customer email while quotes are in progress, so use an address the customer can actually receive. At that point, either keep polling, share homeowner_quotes_request_login_url with the customer, or mint an operator browser link from POST /api/agent/homeowners/dashboard/session.
```sh
POST https://www.coveragecat.com/api/agent/homeowners/quotes
Authorization: Bearer ccop_...
```

- To check one delegated homeowners request, keep polling POST /api/agent/homeowners/quotes with the same uid until status changes.
- To check the status of outstanding delegated homeowners requests across the operator, call GET https://www.coveragecat.com/api/agent/homeowners/dashboard or mint a browser session via POST https://www.coveragecat.com/api/agent/homeowners/dashboard/session.


## 5. Rotate before day 365

Keys expire 365 days after issuance. You can rotate earlier at any time with the current key. The old key stops working immediately.
```sh
curl -X POST https://www.coveragecat.com/api/agent/key/rotate \
  -H "Authorization: Bearer ccop_..."
```

Response shape:

```json
{
  "api_key": "ccop_...",
  "key_prefix": "ccop_...",
  "expires_at": "...",
  "message": "Key rotated. Save the new key — it will not be shown again. Your previous key is now invalid."
}
```


## 6. If you lose the key

Repeat steps 1 and 2. The OTP flow rotates the key on the existing operator record tied to that email instead of creating a duplicate operator.

## Common setup responses

- `400 invalid_email`: The operator email is malformed, disposable, or otherwise invalid for delivery. Use a real mailbox that can receive the OTP.
- `401 invalid_otp`: The submitted code did not match the latest OTP for that operator email. Check for a newer email or request a fresh code.
- `401 otp_expired`: The 10-minute OTP window elapsed. Request a new code and retry confirm.
- `422 validation_error`: One of the optional registration fields failed validation. Shorten or correct organization_name, referral_source_name, contact_name, assistant_email, or use_case_description and retry.
- `429 rate_limited`: OTP request is limited to 3 requests per hour per email. OTP confirm is limited to 5 attempts per 10 minutes per email. Honor the Retry-After header before retrying.
- `500 internal_error or rotation_failed`: A transient server-side failure occurred while sending an OTP, issuing a key, or rotating a key. Retry once, then contact Coverage Cat if it persists.