Reference

Keys and access

The public key, the three kinds of secret key, what each can reach, and how to replace one.

A site has one public key and up to 20 active secret keys: one for each place a key is stored, so each can be revoked on its own.

The public key

pk_ followed by 24 hexadecimal characters. It goes in the browser part (init({ publicKey }), the tag's data-key, the Shopify pixel) and is safe to show: it can only send data, never read any, and the gateway accepts its beacons only from pages on the site's own domain, its www form and its subdomains.

Secret keys

sk_parlox_ followed by 64 hexadecimal characters: 256 random bits. The distinctive prefix makes a leaked Parlox key easy to recognise, by you and by the secret-scanning patterns you configure. The dashboard shows a key's value once, when it is created, and afterwards only its first characters (sk_parlox_1a2b3c4d…) and its name; Parlox stores only a hash of it. Older keys that start with sk_ and no parlox_ keep working.

A secret key goes in Authorization: Bearer <key>, on your server only: never in browser code, in git, or in a variable your frontend build exposes (VITE_…, NEXT_PUBLIC_…).

Access levels

Each key has one access level, chosen when it is created and fixed for its life.

AccessCan sendCan readWhere it goes
Crawler reports onlyReports of automated requests (POST /v1/s)NothingPARLOX_SECRET_KEY, for the server part's middleware. The key a new site gets, every key the install wizard creates, and the form's default
Send: crawler reports and ordersAlso orders, other commerce events and UCP reportsNothingA variable of its own, such as PARLOX_ORDERS_KEY, on the server that posts orders
Send + readThe sameGET /v1/stats, GET /v1/audits, POST /v1/auditsA script or tool of your own, never the server's environment

A key used beyond its access gets 403, and nothing in that request is stored:

  • an order or UCP report with a crawler-reports-only key: This key can only send crawler reports. To record orders or UCP reports, create a send key in the dashboard (Settings → Keys).
  • a read with a send-only key: This key can only send data. Create a key with read access in the dashboard (Settings → Keys).

A key Parlox does not know, or one revoked or expired, gets 401 Invalid secret key.

Why the narrowest key goes in PARLOX_SECRET_KEY

A host's build can often read the server's variables, and a build runs other people's code. So the variable the middleware uses holds a key that can do as little as possible. If a "Crawler reports only" key leaks, whoever holds it can, until you revoke it, add made-up crawler visits to that one site (they can even show as verified, since a server's report states the address it saw) and a made-up count of undelivered reports, which shows as a delivery warning on Install status. Never an order, never a read.

A send key in that variable would end that bound. Keep it in a variable of its own, treated like a payment provider's secret key.

Creating, replacing, revoking

All in the dashboard, Settings → Keys, by an owner or admin of the site's account.

  • Create: a name (one per place the key is stored), an optional note, and the access level. The value is shown once.
  • Replace…: issues a new key with the same name, note and access, and lets the old one keep working for the period you choose (immediately, 24 hours or 7 days), so you can deploy the new one first. A key already being replaced cannot be replaced again.
  • Revoke: stops the key at once, on every gateway instance. Keys are never cached, so there is no delay.

"Last used" is accurate to about an hour. If you think a key leaked, replace it with no grace period, or revoke it.

Remove the install wizard's access to my account (also under Keys) ends the wizard's sign-in, but does not revoke the keys it created; revoke those separately.

Reading with a key

A "Send + read" key returns the same numbers as the dashboard, for scripts and checks:

Terminal
curl -H "Authorization: Bearer $PARLOX_READ_KEY" "https://gateway.parlox.io/v1/stats?days=7"

days is from 1 to 90. POST /v1/audits with {"url": "https://your-site.example/products/x"} runs a page check on a page of your own, verified domain, and GET /v1/audits lists past checks.