Keys and test mode
Publishable keys identify your platform. Every key needs allowed origins; test keys mark sales as test sales.
Publishable keys
Publishable keys start with pk_live_ or pk_test_ and are created in the developer portal under API Keys → Publishable keys. They are safe to ship in browser and mobile code because they can only do one thing: open the CoverPort quote flow for the agent they are linked to. They cannot call the REST API.
The key identifies your platform. Every buyer who starts a quote through it is linked to your agent, every purchase is attributed to you, and any platform fee configured on the key is added on top of the CoverPort price at checkout.
| Prefix | Shows "Test mode" badge | sale.testMode | Use for |
|---|---|---|---|
pk_test_ | Yes | true | Local development, staging, CI |
pk_live_ | No | false | Production |
Whether a card is charged does not depend on the key: only test products (set up on a test agency) use Stripe test mode. A pk_test_ key linked to an agent that sells live products takes real payments. To integrate without real charges, link your test key to an agent with test products and pay with Stripe's test cards.
A key's mode is fixed when it is created. To move from test to live, create a live key and swap it in your code.
Creating a key
In the portal, choose Create publishable key and fill in:
- Name and description. For your own records; the name is shown to buyers as "via name" unless your organisation has a display name.
- Insurance agent. Required. The CoverPort agent whose products the flow offers and who the sale is attributed to. The agent must have a storefront slug; the flow quotes against it.
- Mode. Test or live.
- Platform fee. A percentage and/or fixed amount added on top of the CoverPort charge. The buyer sees the combined price at checkout.
- Allowed origins. The sites that may embed the flow with this key, for example
https://www.acme-freight.com. Required for every key, test or live: the portal will not save a key without at least one. For local development add your dev server's origin, for examplehttp://localhost:3000. See Security. - Appearance. Default primary and secondary colours, light/dark/auto mode, and a logo URL. These apply to every page that uses the key. The
themeoption oncoverport.mount()overrides them per page. See Reference. - Attribution code. Optional. A landing-page code from the seller console; buyers created through this key carry it, so one agent can tell partners or campaigns apart.
The key value is shown in the list and can be copied at any time. Publishable keys are not secrets.
Changing name, fee, origins, appearance or code takes effect on the next quote session. No code change is needed.
Revoking a key
Revoke stops the key immediately: the modal shows an "invalid key" message on any page still using it. Revoked keys stay in the list for reference. Create a new key rather than reusing an old one.
Security
A publishable key on its own can only start a quote for your agent, so leaking it does not expose data or money. Two settings limit what a leaked key can do:
- Allowed origins become a
Content-Security-Policy: frame-ancestorsheader on the hosted flow, so another site cannot frame it with your key, and thecompleteevent is only delivered to those origins. A key with no allowed origins is refused: the modal shows "This publishable key has no allowed origins" instead of the quote flow, and no sale events are sent. - Test keys get no exception. Whether a card is charged does not depend on the key: only test products (set up on a test agency) use Stripe test mode. A
pk_test_key linked to an agent that sells live products takes real payments.
Validation
The SDK checks the key format before it does anything else:
^pk_(live|test)_[A-Za-z0-9]+$If the format is wrong, mount() and open() throw synchronously with a message that names the problem. If the format is right but the key is unknown or revoked, the modal opens and shows an "invalid key" message instead of the quote flow. See Troubleshooting.
Secret keys
Secret keys authenticate server-to-server calls to the REST API and are created on the same portal page under Organization API Keys. They are sent as x-api-key, never accepted by the SDK, and must never appear in client code.
Like publishable keys, a secret key is linked to one insurance agent, and every endpoint only works with that agent's buyers, purchases, certificates and Stripe account. See Keys only see their own agent.