Authentication
Headless API authentication — one header, public and secret keys, the allowed-websites rule and every failure code.
Base URL:
https://client.usequeek.com/v1Every request carries the connection's API key in X-Client-Key, and should ask for JSON:
curl https://client.usequeek.com/v1/store/info \
-H "X-Client-Key: pk_live_your_key_here" \
-H "Accept: application/json"There is no OAuth flow and no token exchange for the store itself. The key is the credential, and it belongs to one store: a key never reaches another merchant's data. Reading the catalogue and building a cart need nothing else. Signed-in customer features (account, saved addresses, wishlist, order history) add a customer token on top, described below.
Two kinds of key
The merchant makes both in the dashboard, under Channels → Headless API → Connect a site or app (see the quickstart). Every key belongs to one connection, and the connection's type decides which keys it holds and which rules apply. The same keys are also listed under Settings → Connections.
pk_live_… — public
Made to be shipped in browser and app code, where anyone can read it. Because the key itself cannot be a secret there, what protects it depends on the connection type:
| Connection type | What is checked |
|---|---|
| Website | The browser's Origin. The key only works from the https:// websites listed on the connection. * is not accepted. While Development mode is on, any website works. |
| Testing on my computer | The same list, which always includes this computer (http://localhost, any port). Dev stores only, with pk_test_… keys. |
| Mobile app | Nothing: an app sends no Origin, and a browser using the key is refused because the connection lists no websites. |
| Server or backend | Nothing for the public key (plus a secret key, below). |
| AI agent | Nothing, but the key can browse products and build carts only. Anything else is 403 agent_access_denied. |
Calling a website key from a terminal or a test runner? Send a listed website yourself:
curl https://client.usequeek.com/v1/store/products \
-H "X-Client-Key: pk_live_your_key_here" \
-H "Origin: https://shop.example.com"Keys made before the Headless API
A store that already had a public key finds it under Channels → Headless API as a connection
named Default, with the same key and the same websites. A key whose list is * keeps working
from any origin and from none until the merchant edits its websites; after that, * cannot be
added again. New connections never accept *: they list exact websites.
Building in AI tools
AI site builders serve the page they generate from a random address that changes between
sessions, so no list of websites can name it. A Website connection has a Development mode
switch for exactly that. While it is on, the connection's public key works from any website, from
none (a terminal, a script) and from a sandboxed page (Origin: null).
- In Channels → Headless API, choose Connect a site or app → Website.
- Turn on Development mode. The website address becomes optional: there is no domain yet.
- Copy the public key (or Copy for AI) and paste it into your AI tool.
- Build. The connection page shows a warning and the time left. It lasts 14 days; Renew 14 days starts a fresh window.
- When the site has a domain, add the real
https://address under Websites allowed to use this key, then turn Development mode off. The listed websites apply again and a random address is refused withorigin_not_allowed.
It is your live store
A live store has no test payment mode: an order a prototype creates is a real order, and a card payment is a real charge. Build and test checkout on a dev store, which has a simulated payment page, and do not complete payments from a prototype made on a live store.
- Only the public key is affected, only the website check, and only for a Website
connection. A secret key, the plan requirement and what the public key can do do not change.
*is still never accepted as a website. - The window is checked on every request, so it ends on its date without anything to run. After it
ends, or once the switch is off, a request from an unlisted website fails with
origin_not_allowed, and one with no website address orOrigin: nullwithorigin_required. Both messages point to the switch. - After checkout, a buyer is sent back only to a page the merchant listed. In development mode an
https://return link is also honoured when it is on exactly the website the request came from. A request with no website address orOrigin: nullhas none, so the buyer is not sent back: they land on Queek's own thank-you page. In development mode this link trusts the website that opened the checkout, so use it only while building.
sk_live_… — secret
For servers, SSR and build-time fetches — anywhere the key is not handed to a visitor. A secret
key needs no Origin. It is shown once, when a Server or backend connection is created
or its secret key is replaced. It must never appear in a browser bundle, a mobile app, a public
repository, or a client-side environment variable. On the client API it holds no scopes: it
reaches the same public endpoints as a public key, with a per-plan request quota. It does not
open the Merchant API, which takes its own scoped key.
Rule of thumb
If a visitor's device can read the string, it has to be a pk_live_ key on a Website,
Mobile app or AI agent connection. Server code gets a Server or backend connection.
Replacing and turning off keys
Replace key makes a new key and both keep working until the old one is turned off, so a live site is never down. Turn off stops a key on its next request. See Manage a connection.
Customer sign-in
Customer features use a second credential beside the store key: a customer access token. Sign a
shopper in with one of the Auth operations, for example
email and password, or a phone number with a one-time
code. The reply carries the tokens:
{
"status": "success",
"message": "Signed in",
"data": {
"access_token": "cli_…",
"refresh_token": "clr_…",
"token_type": "Bearer",
"expires_in": 3600,
"refresh_expires_in": 2592000,
"user": { "id": "…", "name": "…", "email": "…" }
}
}Send the access token as Authorization: Bearer <access_token> alongside X-Client-Key on
account, address, wishlist and order operations. A token is bound to one store: one issued for
another store answers 403. Refresh it with POST /auth/token/refresh before it expires (expires_in and
refresh_expires_in give the lifetimes in seconds: one hour and thirty days in the reference example), and call
POST /auth/logout on sign-out. When a customer token is present, the cart follows the
customer and X-Cart-Session is ignored.
Keep customer tokens out of URLs and logs.
What the browser is allowed to send
Cross-origin requests may carry Authorization, X-Client-Key, X-Cart-Session,
Idempotency-Key, If-None-Match, X-Request-Id, Content-Type and Accept. Anything else
is not part of the CORS contract. Responses expose ETag, Retry-After, X-RateLimit-*,
X-Request-Id and, from a dev store, X-Queek-Mode to browser code.
A request from a website that is not allowed is refused without CORS headers, so a browser
reports a CORS error in its console instead of the 403 body. The fix is on the connection,
not in your code: see
Websites allowed to use a key.
Rate limits
Two ceilings apply, and exceeding either answers 429 too_many_requests with Retry-After:
| Ceiling | Value | Applies to |
|---|---|---|
| Shared bucket | 180 requests per minute | Every key, per key and IP (or storefront origin and IP when no key is sent) |
| Plan quota | free 60, social_media 120, starter 120, growth 240, scale 1,200, enterprise 2,400 per minute | sk_live_ private keys only, from the store's plan |
A public key is shared by every visitor of the store, so it has no plan quota: only the shared
bucket applies, per visitor IP. Successful responses carry X-RateLimit-Limit and
X-RateLimit-Remaining, so read X-RateLimit-Remaining instead of guessing, and wait for
Retry-After seconds on a 429.
Reads answer with an ETag and Cache-Control: private, no-cache. Send the value back as
If-None-Match and an unchanged resource costs you a 304 instead of a payload.
When authentication fails
The reply carries error_code — it names exactly what to fix. The same refusals appear in plain
English on the connection's Problems card.
error_code | Status | What it means |
|---|---|---|
client_key_required | 401 | No X-Client-Key header was sent. |
invalid_client_key | 401 | The key is unknown, or it was turned off. Check the connection under Channels → Headless API. |
origin_required | 403 | A website key was used with no Origin, or with Origin: null from a sandboxed frame. Server code needs a Server or backend connection; an app needs a Mobile app connection; a build in an AI tool needs Development mode on a Website connection. |
origin_not_allowed | 403 | The Origin is not on the connection's list of allowed websites. The merchant adds it with one click on the Problems card. |
plan_inactive | 403 | The live store's plan does not include API access. A dev store always has it. |
api_key_mode_mismatch | 401 | A _test_ key on a live store, or a _live_ key on a dev store. |
agent_access_denied | 403 | An AI agent key tried something beyond browsing products and building carts. |
storefront_password_required | 401 | The store is a dev store and the request carried no valid storefront token. |
route_not_available | 404 | Not part of this API. The endpoints are exactly those in the reference. |
An origin_* failure is the merchant's to fix, not yours: they add your website to the
connection. Never ask for * — it is not accepted; for a build in an AI tool the merchant can turn on Development mode. See
versioning & errors for the full envelope.
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.
Custom fields (metafields)
The store's own typed fields on products, variants, collections, blog posts, orders and customers — definitions, the two access switches, how to write and read them, webhooks and limits.