Authentication
One secret key, sent on every request. It decides which agent you sell for.
Create a key
- Sign in to the developer portal.
- Open API Keys and choose Create key. Give it a name and description that will make sense to a teammate a year from now.
- Choose the insurance agent the key sells for. A key without an agent is refused with
403 key_not_linked. - Copy the key. It is shown once. If you lose it, rotate it.
- Ask us to turn the API on for the key. The API is off by default: until it is enabled, every request with the key returns
403witherror.code: "api_not_available". Email api-support@coverport.io with the key's name (never the key itself) and the agent it sells for; we reply when it is on.
The agent decides everything the key can see: the buyers it signs up are connected to that agent, it lists only the products that agent offers, and it finds only purchases that agent sold.
Send it
Send the key as x-api-key, and the API version as CoverPort-Version, on every request.
curl "https://api.coverport.io/api/buyers?email=dispatch@acme-freight.com" \
-H "x-api-key: $COVERPORT_API_KEY" \
-H "CoverPort-Version: 2026-11-20"What a rejected key looks like
A missing, unknown, frozen or deleted key is refused before it reaches the API, with the usual error shape:
HTTP/1.1 403 Forbidden
{ "error": { "code": "invalid_api_key", "message": "Send a valid API key in the x-api-key header. This one is missing, unknown, frozen or deleted." }, "requestId": "…" }A valid key that is not enabled for the API yet gets 403 with error.code: "api_not_available".
A valid key asking for a buyer or purchase that belongs to another agent gets 403 with error.code: "forbidden". A buyer connected to several agents can be read by any of their keys.
Rotate, freeze, delete
All three are in the portal under API Keys.
- Rotate issues a new value and keeps the old one working for a grace period, so you can deploy the new one without downtime.
- Freeze stops a key immediately and reversibly. Use it if you suspect a leak.
- Delete revokes the key permanently.
Keep it server-side
A secret key can sign up buyers and create quotes in your name. Never ship it in a browser bundle, a mobile app, or a public repository. For anything that runs on a buyer's device, use the SDK with a publishable key (pk_…) instead.
Rate limits
Limits are per API key, across everything the key calls:
| What | Limit |
|---|---|
| All requests | About 5 a second, with short bursts of up to 10 |
POST /quotes | 2 a second |
POST /buyers that creates a buyer | 1 a second, and the sign-up limit of 30 buyers an hour and 100 a day (429 signup_limit) |
| Daily quota | 100,000 units a day, reset at 00:00 UTC |
Why "about": behind the API, each request calls one to three CoverPort services with your key, and the gateway counts those calls too. The limits above are what that comes to for typical requests. The same goes for the quota: a request uses 2 to 4 units, so 100,000 units is roughly 25,000 to 50,000 requests a day.
Over a per-second limit you get 429 with error.code: "rate_limited" and always a Retry-After header (seconds). Wait that long, then retry. If many requests are waiting, spread them out rather than retrying them all at once.
A key that uses up its daily quota gets 429 quota_exceeded, with no Retry-After: retrying will not help until 00:00 UTC. Email api-support@coverport.io if you need more.