Keys and access
The public key, the three kinds of secret key, what each can reach, and how to replace one.
On this page
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.
| Access | Can send | Can read | Where it goes |
|---|---|---|---|
| Crawler reports only | Reports of automated requests (POST /v1/s) | Nothing | PARLOX_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 orders | Also orders, other commerce events and UCP reports | Nothing | A variable of its own, such as PARLOX_ORDERS_KEY, on the server that posts orders |
| Send + read | The same | GET /v1/stats, GET /v1/audits, POST /v1/audits | A 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:
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.