Skip to main content

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.

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: 
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:
ScopeWhat it permits
catalog:readRead products, collections, search, sitemap
cart:writeCreate and modify carts
checkout:createIssue chk_ checkout sessions
customer:authRegister, 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: 
Deprecation: true
Sunset: Wed, 31 Dec 2026 23:59:59 GMT
Migrate to X-Stella-Token before the sunset date.