> ## Documentation Index
> Fetch the complete documentation index at: https://docs.quickshops.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Authenticating with the Quickshops Headless API

> Learn how to create and use your API key to authenticate requests to the Quickshops Headless API, including rotation best practices.

<Note>
  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](/mcp/overview). Developers use the same keys for custom storefront code.
</Note>

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

<Info>
  API keys require an active **Pro** subscription. On the Free plan, **Settings → API keys** shows an upgrade prompt instead of the key form.
</Info>

<Steps>
  <Step title="Upgrade to Pro (if needed)">
    Open **Account → Billing** in your dashboard and subscribe to Pro if you are not already on the plan.
  </Step>

  <Step title="Open your dashboard">
    Log in to your Quickshops dashboard.
  </Step>

  <Step title="Go to Settings → API keys">
    Navigate to **Settings** in the sidebar, then select **API keys**.
  </Step>

  <Step title="Issue a key">
    Click **Issue key**, give it a name, choose an optional expiry, and confirm.
  </Step>

  <Step title="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.
  </Step>
</Steps>

<Warning>
  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.
</Warning>

## Using your API key

Pass the key as a bearer token in the `Authorization` header on every request.

```bash theme={null}
curl https://api.quickshops.app/v1/products \
  -H "Authorization: Bearer qk_your_key_here"
```

Your environment configuration should look something like this:

```bash theme={null}
HEADLESS_API_KEY=qk_...
```

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

| HTTP status | Code           | Cause                                                                         |
| ----------- | -------------- | ----------------------------------------------------------------------------- |
| `401`       | `UNAUTHORIZED` | The bearer token is missing, malformed, or has been revoked.                  |
| `403`       | `FORBIDDEN`    | The request origin is blocked for this key, or the store owner is not on Pro. |
| `429`       | `RATE_LIMITED` | The key or endpoint has exceeded its request limit. Retry later.              |

All errors are returned as JSON with `error` and `code` fields. See [Overview](/api/overview) for the full error format.