> ## 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.

# Authentication overview

> Three token types covering merchants, customers, and agents — all on the same surface.

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
```

| Token    | Used by                                   | Lifetime                                   | Revocable                  | Audit-logged         |
| -------- | ----------------------------------------- | ------------------------------------------ | -------------------------- | -------------------- |
| `stk_…`  | Your storefront server / SDK              | Indefinite                                 | Yes (instant)              | Yes (mutations only) |
| `cust_…` | A logged-in customer's session            | Short, renewable                           | Yes (instant)              | Yes (mutations only) |
| `agt_…`  | An AI agent acting on a customer's behalf | Bounded by `expires_at` and `budget_cents` | Yes (customer or merchant) | **Yes (every call)** |

## Design principles

<AccordionGroup>
  <Accordion title="Opaque tokens, server-side lookup — not JWTs">
    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.
  </Accordion>

  <Accordion title="Idempotency on every mutation">
    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.
  </Accordion>

  <Accordion title="Multi-tenant by construction">
    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.
  </Accordion>

  <Accordion title="Tokens never logged">
    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.
  </Accordion>
</AccordionGroup>

## Choosing the right token

<CardGroup cols={3}>
  <Card title="Storefront token" icon="store" href="/auth/storefront-token">
    Calling Stella from your server (Next.js route, Cloudflare Worker,
    Express handler). Lives in your secrets manager.
  </Card>

  <Card title="Customer token" icon="user" href="/auth/customer-token">
    Acting as a logged-in shopper. Returned by `POST /customer/login`.
    Stored in browser session/cookie.
  </Card>

  <Card title="Agent token" icon="robot" href="/auth/agent-token">
    An AI agent shopping on a customer's behalf. Minted via OAuth
    Device Authorization (RFC 8628) consent flow.
  </Card>
</CardGroup>

## Headers cheat sheet

```http theme={null}
# 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.