Queek docs

Authentication

Headless API authentication — one header, public and secret keys, the allowed-websites rule and every failure code.

Base URL:

https://client.usequeek.com/v1

Every 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 typeWhat is checked
WebsiteThe 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 computerThe same list, which always includes this computer (http://localhost, any port). Dev stores only, with pk_test_… keys.
Mobile appNothing: an app sends no Origin, and a browser using the key is refused because the connection lists no websites.
Server or backendNothing for the public key (plus a secret key, below).
AI agentNothing, 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).

  1. In Channels → Headless API, choose Connect a site or app → Website.
  2. Turn on Development mode. The website address becomes optional: there is no domain yet.
  3. Copy the public key (or Copy for AI) and paste it into your AI tool.
  4. Build. The connection page shows a warning and the time left. It lasts 14 days; Renew 14 days starts a fresh window.
  5. 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 with origin_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 or Origin: null with origin_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 or Origin: null has 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:

CeilingValueApplies to
Shared bucket180 requests per minuteEvery key, per key and IP (or storefront origin and IP when no key is sent)
Plan quotafree 60, social_media 120, starter 120, growth 240, scale 1,200, enterprise 2,400 per minutesk_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_codeStatusWhat it means
client_key_required401No X-Client-Key header was sent.
invalid_client_key401The key is unknown, or it was turned off. Check the connection under Channels → Headless API.
origin_required403A 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_allowed403The Origin is not on the connection's list of allowed websites. The merchant adds it with one click on the Problems card.
plan_inactive403The live store's plan does not include API access. A dev store always has it.
api_key_mode_mismatch401A _test_ key on a live store, or a _live_ key on a dev store.
agent_access_denied403An AI agent key tried something beyond browsing products and building carts.
storefront_password_required401The store is a dev store and the request carried no valid storefront token.
route_not_available404Not 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.

On this page