Skip to main content
API keys are a Pro plan feature. Create them in the dashboard under Settings → API keys after upgrading from Account → Billing. Sellers use keys to manage their store from Claude or Cursor. Developers use the same keys for custom storefront code.
Every request to a protected Quickshops Headless API endpoint must include an Authorization header with a bearer token containing your headless API key. Keys are issued from your Quickshops dashboard and always begin with qk_. Keys are verified through Unkey on every request.

​
Creating an API key

API keys require an active Pro subscription. On the Free plan, Settings → API keys shows an upgrade prompt instead of the key form.
1

Upgrade to Pro (if needed)

Open Account → Billing in your dashboard and subscribe to Pro if you are not already on the plan.
2

Open your dashboard

Log in to your Quickshops dashboard.
3

Go to Settings → API keys

Navigate to Settings in the sidebar, then select API keys.
4

Issue a key

Click Issue key, give it a name, choose an optional expiry, and confirm.
5

Copy the key immediately

The plaintext key is only shown once. Copy it and store it in a secure location such as an environment variable or a secrets manager. You cannot retrieve it again after leaving this screen.
Never expose your API key in client-side code or public repositories. Use it only in server-side environments where it cannot be accessed by end users.

​
Using your API key

Pass the key as a bearer token in the Authorization header on every request.
Your environment configuration should look something like this:
Then read the variable in your server-side code and include it in each request header. Do not hard-code the key in source files. If you use the TypeScript SDK, construct Quickshops from @quickshops/sdk inside a server-only module and pass only response data to your UI. Import storefront types from @quickshops/starter-templates in client components when needed.

​
Server-side usage

Use API keys only in trusted server environments (API routes, server actions, backend jobs). Missing or invalid keys return 401 with code UNAUTHORIZED. Never expose keys in client-side code or public repositories. On hosted Quickshops storefronts, cart session IDs in browser storage are sensitive — treat them like bearer tokens for cart access.

​
Origin restrictions

API keys can optionally restrict which browser origins may call the API. When allowed origins are configured on a key, requests must include a matching Origin header or they are rejected with 403 and code FORBIDDEN. This is useful when calling the API from a browser-based client. Server-to-server requests typically do not send an Origin header and are not affected unless origins are configured.

​
Key rotation

Rotate your keys regularly to reduce the blast radius of a potential compromise.
  • Rotate every 30–60 days as a baseline.
  • Issue the new key, deploy your integration with the new key, then immediately revoke the old key.
  • Verify that all services using the old key have been updated before revoking it.
You can revoke a key at any time from Settings → API keys in your dashboard.

​
Common authentication errors

All errors are returned as JSON with error and code fields. See Overview for the full error format.