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

# Storefront Access Token

> The merchant-tier token your server uses to call Stella.

A **Storefront Access Token** (`stk_…`) authenticates your storefront
server to Stella. One token belongs to one merchant; calls made with
it can only see that merchant's data.

## Mint a token

In the dashboard at **Settings → Storefront access tokens**:

1. Click **Create token**.
2. Name it (`production`, `kasa-staging`, etc.).
3. Add the origins your server-side fetcher will call from. Leave
   empty to disable Origin enforcement (server-only callers don't send
   an `Origin` header anyway).
4. Click **Create**. Copy the `stk_live_…` value — it's shown once.

## Use it

Pair it with the merchant's `site_id` on every call:

```bash theme={null}
curl -H "X-Site-ID: kasa" \
     -H "X-Stella-Token: stk_live_..." \
     https://api-dev-app.stella-commerce.com/api/storefront/products
```

## Scopes

Default scopes on a freshly minted token:

| Scope             | What it permits                              |
| ----------------- | -------------------------------------------- |
| `catalog:read`    | Read products, collections, search, sitemap  |
| `cart:write`      | Create and modify carts                      |
| `checkout:create` | Issue `chk_` checkout sessions               |
| `customer:auth`   | Register, log in, recover-password endpoints |

Token-level scope narrowing isn't user-configurable yet; if you need a
read-only token for your CMS preview environment, mint a separate token
and revoke it on rotation.

## Origin enforcement

If `allowed_origins` is non-empty on the token, requests must carry an
`Origin` header matching one of the listed values. Mismatch → 403.

This is the layer that protects against stolen tokens being used from a
different domain. Server-to-server callers (Next.js route handlers,
Cloudflare Workers, etc.) don't send `Origin` so they aren't affected.
Browser callers always send it.

## Rate limits

Per-token, per-minute, applied at the edge:

* **Default**: 60 requests/min, 60-burst token bucket
* Headers: `RateLimit-Limit`, `RateLimit-Remaining`, `RateLimit-Reset`
* Overflow: `429 Too Many Requests` + `Retry-After`

Need higher limits? Contact us — they're configurable per merchant.

## Rotation and revocation

In the dashboard:

* **Rotate** issues a new value and revokes the old one. Use this on a
  fixed cadence or after a suspected leak.
* **Revoke** invalidates the token immediately. Calls fail with `401`
  starting on the next request.

## Legacy `X-API-Key` callers

Older integrations using `X-API-Key + X-Site-ID` continue to work
through a deprecation window. Responses include:

```http theme={null}
Deprecation: true
Sunset: Wed, 31 Dec 2026 23:59:59 GMT
```

Migrate to `X-Stella-Token` before the sunset date.