Keys and authentication

Publishable key and secret key

The publishable key travels in the URL as ?key=. It is public by design: it is in your page source, and it works only from the origins listed on it. The secret key travels as Authorization: Bearer <key> and is for your server only. A browser cannot even send it to the service: Authorization is not in the CORS allow-list.

Allowed origins

Each publishable key carries a list of up to 20 origins: scheme, host and port exactly as the browser sends them, such as https://shop.example.com. A request from any other origin is refused with 403 origin_not_allowed, the preflight included, and the service never answers with Access-Control-Allow-Origin: *. The list is a signal, not authentication: the real defences are the server-side price and the rate limits.

Test keys

A live shop can create up to 3 test keys (pk_test_…, sk_test_…). A test key prices on your newest validated draft, so you can try a change before you publish it. It is not billed, its orders send no webhook and no e-mail, and it expires after 30 days. Test and live never mix: a test quote verifies only under a test secret key, a test order is visible only to a test key, and a live key never sees one. A test key may list http://localhost as an origin.

The project token

Saved projects are scoped to a shopper, not to a login. The first POST /cfg/v1/projects issues a random token (cfgpt_…) and returns it once; the embed keeps it and sends it as X-Cfg-Project-Token on every later project call. Another shopper's token, another shop's key and an unknown id all answer the same 404.

Rotation without downtime

Rotation is done in the console, and every kind has an overlap so nothing breaks while you switch.

• Publishable key: the new key keeps the same origin list; the old one keeps working for 168 hours by default (at most 720).
• Secret key: shown once; the old key keeps authenticating for 24 hours by default (at most 720).
• Quote-signing key: the new key signs from now on; quotes the old key signed still verify and can still be ordered for up to 31 days.
• Webhook secret: during a switch both secrets sign each delivery for 7 days, as two v1= values, so your receiver can hold either.

What never goes in a browser

The secret key and the webhook secret (whsec_…). Keep them in your server's environment, never in a page, a repository or a log. If one leaks, rotate it in the console.