Manage a connection
Replace or turn off a Headless API key, set allowed websites and after-checkout return links, read the Is it working status and plain-English errors, go live from a dev store, or disconnect.
A connection is one website, mobile app, server or AI agent that uses a store through the Headless API. Connections live in the Queek dashboard under Channels → Headless API. Each one holds its keys, the websites allowed to use them, where customers return after checkout, and its own status and sales figures. The same keys are also listed under Settings → Connections, which is where any other API key is managed.
Connections are managed in the dashboard only. Neither the Merchant API nor an API key can create, change or remove one, and an AI coding tool cannot do it for you: ask the merchant to open the page.
Managing connections needs the same permissions as managing API keys (read, create, update and revoke). A team member without them does not see the page.
Keys
Every connection has a public key. A connection of type Server or backend also has a secret key.
| Public key | Secret key | |
|---|---|---|
| Looks like | pk_live_… (pk_test_… on a dev store) | sk_live_… (sk_test_… on a dev store) |
| Safe in browser or app code | Yes. A website key only works from the websites you list. | Never. Servers only. |
| Visible later | Yes, always on the connection page | No. Shown once, when it is created or replaced. Replace it if you lose it. |
| Request quota | Shared by every visitor | Per key, from the store's plan |
Replace a key
Replace key makes a new key and keeps the old one working. Both work until you press Turn off on the old one, so a live site never goes down while you move it to the new key:
- Press Replace key (on a server connection, Replace public key or Replace secret key).
- Copy the new key. A secret key is shown only now.
- Put the new key into your site, app or server and deploy it.
- When nothing uses the old key any more, press Turn off on it.
A connection holds at most two working keys of each kind. While two are working, Replace key asks you to turn the old one off first. The newer key is marked as current; use that one.
Turn off a key
Turn off stops a key on its next request. Anything still using it fails with
401 invalid_client_key until it is given another key. Turning a key off cannot be undone: make
a new one with Replace key.
Websites allowed to use a key
A website or testing connection lists the websites its public key may be used from. Browsers always say which website a request comes from, and Queek only answers the websites on the list.
- https only, and the exact address:
https://shop.example.com. Use the address as the visitor sees it, with no page path.https://www.shop.example.comandhttps://shop.example.comare two different websites; list both if you use both. - A wildcard (
*) is never accepted. Neither ishttp://, except for the computer you test on (below). Allowing every website would let anyone copy your public key into their own site. - A website connection needs at least one website. You can list up to 20.
- A Testing on my computer connection always allows this computer (
http://localhost, on any port, and127.0.0.1), plus anyhttps://preview address you add. Nothing else is plainhttp://. - Changes apply to the connection's live public keys straight away.
A mobile app, server or AI agent connection lists no websites. Those programs send no website address, and a browser that tried to use their key would be refused.
A blocked website looks like a CORS error in the browser
When a browser's request is refused because its website is not on the list, the browser hides
the answer and reports a CORS error in the console. Do not change the code: add the website
to the list. Repeat the call with curl and an Origin header to read the real
origin_not_allowed, or open Problems on the connection page.
The fix is one click. When a request from an unlisted website reaches Queek, the Problems card shows A request from shop.example.com was blocked — it is not an allowed website with an Allow shop.example.com button. Press it only for a website you own.
Development mode
A Website connection can be put in Development mode while an AI tool builds the site from a random address: for 14 days any website can use its public key, and no website needs listing yet. The connection page shows a warning with the time left and a Renew 14 days button. Turn it off, with your real websites listed, when the site is ready. It is your live store, so orders made from a prototype are real. The steps, and what it does not change, are in Authentication.
After checkout, send customers back to
Each connection can list up to 10 pages (or app links) customers return to once they have paid. Leave it empty and customers see Queek's own thank-you page.
- A website connection lists full
https://addresses of its own site, for examplehttps://shop.example.com/thanks. - A mobile app connection can also list its app link, for example
myapp://checkout/done. Links that start withjavascript:,data:,file:and similar are never accepted. - A testing connection may also list
http://localhost:…addresses and app links. - An address cannot hold a login (
user:password@), spaces, backslashes,//or..in its path.
The list is an allowlist, not a template. A request can name one of the pages with
return_url, and it is used only when it sits on the same website and under the path of a
listed entry. Anything else is ignored and the customer returns to the first listed page, or to
Queek's own page if there is none. The rule is checked again at the moment the customer is sent
back, so a page you remove stops working at once. Queek adds ?queek_order= and the order's
number to the page it sends the customer to.
In Development mode a link on exactly the website the request came from is also honoured, but only when that request sent a website address: a sandboxed page (Origin: null) or a request with none has no website to return to, so the customer is not sent back. That link trusts the website that opened the checkout, so use it only while building.
Is it working?
The top of the connection page shows one of two states:
| State | What it means |
|---|---|
| Waiting for your site… (or your app, your server, your AI agent, your test site) | No request has been accepted for this connection's keys yet. It changes by itself on the first one. |
| Connected — first request … ago | At least one request was accepted. The line below says when a key was last used. |
Orders and revenue counts orders that were made from a cart this connection's key built, over the last 30 days: how many orders, how many are paid, and the revenue of the paid ones in the store's currency. A cart's first connection keeps the credit.
Problems and plain-English errors
The Problems card lists the last requests that Queek refused for this connection, newest first, so nobody has to read server logs. It keeps 20 entries for 7 days, and the same problem seen again within half a minute is counted once. A refusal is only listed when the request carried one of this connection's keys, so an unknown key never appears.
| What the card says | Error your code sees | What to do |
|---|---|---|
| A request from a website was blocked — it is not an allowed website. | 403 origin_not_allowed | Press Allow …, or add the website under Websites allowed to use this key. |
| A request that did not say which website it came from was blocked. | 403 origin_required | A website key was used by code that sends no website address (a server, a script, an app). Use a Server or backend or Mobile app connection for that code. |
| A request used a key that has been turned off. | 401 invalid_client_key | Give the site or app the connection's current key. |
| A request used a dev store's key on a live store, or a live key on a dev store. | 401 api_key_mode_mismatch | Use the key from the connection on the store you mean. |
| Requests were blocked because your plan does not include API access. | 403 plan_inactive | Upgrade the live store's plan, or test on a dev store. |
| Too many requests came in with this key in one minute. | 429 too_many_requests | Slow down and wait for Retry-After seconds. |
| An AI agent tried to do something its key is not allowed to do. | 403 agent_access_denied | An AI agent key can browse and build carts only. |
The error codes are listed in Versioning & errors.
The plan
The public API works for a live store only while the store has an active paid website plan,
and always for a dev store. A connection can still be created on a live store
without a plan. It then answers 403 plan_inactive and its page shows This store's plan does
not include API access. Upgrade to use this connection. until the plan is active.
Go live from a dev store
Build first with a Testing on my computer connection on a dev store. When the site works:
- Open the testing connection and press Go live.
- Choose the live store, what you are building (website, mobile app, server or AI agent), and,
for a website, its
https://address. - Queek creates a new connection on the live store with live keys. Nothing is converted: a dev store's connection can never become a live store's. Return links that still fit the new type are copied across.
- Replace the
pk_test_key in your site with the new connection's live key (pk_live_, or thesk_live_secret key if you chose Server or backend). Nothing else in your code changes. - Disconnect the testing connection when you no longer need it. It keeps working until you do.
You must belong to the live store and be allowed to create connections there. Remember the plan: the live store needs an active paid website plan.
Disconnect
Disconnect turns off every key of the connection at once. The site or app using it stops working on its next request, the connection leaves the list, and orders it brought in stay counted against it. This cannot be undone: connect again to get new keys.
Uninstall Headless API
Uninstalling Headless API from the Apps window disconnects every connection of the store at once: all their keys stop working on their next request and the page leaves the sidebar. Your products, orders and settings are kept. Installing it again starts with no connections, so connect each site or app again.
Related
Rules for AI builders
The rules an AI tool (Claude, ChatGPT, Cursor, Lovable, Bolt, v0) must follow when it builds a website, app, server or agent on a Queek store through the Headless API.
Deploy your headless site
Put a site built on the Headless API on Vercel, Netlify or Cloudflare. Pick Server or Website connection by build type, set the keys on the host, use the production address, then go live from a dev store.