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.

Stella’s authentication is built around a three-tier token hierarchy. Each tier represents a different caller and carries a different authority over a customer’s data and budget.

​
The three tiers

MERCHANT          →  Storefront Access Token (stk_…)
                     scope: catalog:read, cart:write,
                            checkout:create, customer:auth
                     header: X-Stella-Token

CUSTOMER (login)  →  Customer Access Token (cust_…)
                     scope: customer:self, orders:read,
                            addresses:write
                     header: Authorization: Bearer cust_…
                     short-lived, renewable, revocable

CUSTOMER delegates →  Agent Capability Token (agt_…)
TO AGENT             scope: act-as customer X, budget ≤ $Y,
                            until time Z, categories ⊆ {…}
                     header: Authorization: Bearer agt_…
                     every action audit-logged
                     hard-capped by budget + expiry
TokenUsed byLifetimeRevocableAudit-logged
stk_…Your storefront server / SDKIndefiniteYes (instant)Yes (mutations only)
cust_…A logged-in customer’s sessionShort, renewableYes (instant)Yes (mutations only)
agt_…An AI agent acting on a customer’s behalfBounded by expires_at and budget_centsYes (customer or merchant)Yes (every call)

​
Design principles

Tokens are random opaque strings stored as argon2id hashes in Postgres. Verification is a hash + lookup, not signature verification. This buys instant revocation, server-controlled payload, and smaller wire size — at the cost of a database round-trip per request. Easy trade-off at our scale.
Every mutating endpoint requires an Idempotency-Key header (any UUID is fine). Replays of the same key within 24 hours return the cached response, so retries — whether from a flaky network or an AI agent’s retry loop — are always safe.
Every query is filtered by site_id, drawn from the token’s metadata. No endpoint can return cross-tenant data — there’s no code path that elides the filter.
Token values appear in server-side logs zero times — only token_id references after hash-lookup. Origin/UA/IP are logged for audit; the token itself never is.

​
Choosing the right token

Storefront token

Calling Stella from your server (Next.js route, Cloudflare Worker, Express handler). Lives in your secrets manager.

Customer token

Acting as a logged-in shopper. Returned by POST /customer/login. Stored in browser session/cookie.

Agent token

An AI agent shopping on a customer’s behalf. Minted via OAuth Device Authorization (RFC 8628) consent flow.

​
Headers cheat sheet

# Storefront (your server calling Stella)
GET /api/storefront/products HTTP/1.1
Host: api-dev-app.stella-commerce.com
X-Site-ID: kasa
X-Stella-Token: stk_live_...

# Customer (logged-in shopper)
GET /api/storefront/customer/me HTTP/1.1
Host: api-dev-app.stella-commerce.com
X-Site-ID: kasa
X-Stella-Token: stk_live_...
Authorization: Bearer cust_...

# Agent (AI acting on a customer's behalf)
POST /api/agent/intent/find-and-buy HTTP/1.1
Host: api-dev-app.stella-commerce.com
Authorization: Bearer agt_...
Idempotency-Key: <uuid>
Content-Type: application/json
Note the storefront token (X-Stella-Token) is always present for storefront-surface calls, even when a customer or agent token is also attached. The merchant-tier token identifies the tenant; the customer/agent token identifies the caller within that tenant.