Customer Access Token

A Customer Access Token (cust_…) represents a logged-in shopper. It’s scoped to one customer within one merchant; you cannot use a customer token across merchants.

Get one

curl -X POST \
     -H "X-Site-ID: kasa" \
     -H "X-Stella-Token: stk_live_..." \
     -H "Content-Type: application/json" \
     -d '{"email": "shopper@example.com", "password": "..."}' \
     https://api-dev-app.stella-commerce.com/api/storefront/customer/login

{
  "access_token": "cust_01HXYZ...",
  "expires_at": "2026-05-08T13:00:00Z",
  "customer": { "id": "...", "email": "shopper@example.com" }
}

The same shape is returned by POST /api/storefront/customer/register.

Use it

Customer tokens go in the Authorization header alongside the storefront token. The merchant-tier token identifies the tenant; the customer token identifies the shopper within that tenant.

curl -H "X-Site-ID: kasa" \
     -H "X-Stella-Token: stk_live_..." \
     -H "Authorization: Bearer cust_01HXYZ..." \
     https://api-dev-app.stella-commerce.com/api/storefront/customer/me

What it permits

Endpoint family	Verbs
`/customer/me`	GET, PATCH
`/customer/me/orders`	GET (list, detail)
`/customer/me/addresses`	GET, POST, PATCH, DELETE, set-default
`/customer/me/agent-consent`	GET, POST (approve/deny)
`/customer/me/agents`	GET (list), DELETE (revoke), audit

Lifetime

Customer tokens are short-lived (default: 24 hours) and renewable via POST /api/storefront/customer/token/renew. Renewal rotates the value and extends the expiry; the old value is revoked immediately.

Revocation

Three paths:

Customer logs out — POST /customer/logout revokes the current token.
Customer revokes a session — from the dashboard’s “Active sessions” panel (Phase 3-A).
Merchant revokes a session — same panel, merchant-side.

Revocation takes effect on the next request.

Account lockout

After repeated failed login attempts the account locks. The dashboard’s customer detail page shows lockout state; the Reset failures button clears it.

Recovery flow

# Step 1 — request a reset email
curl -X POST -H "X-Site-ID: kasa" -H "X-Stella-Token: stk_live_..." \
  -d '{"email": "shopper@example.com"}' \
  https://api-dev-app.stella-commerce.com/api/storefront/customer/recover

# Step 2 — consume the reset token from the email
curl -X POST -H "X-Site-ID: kasa" -H "X-Stella-Token: stk_live_..." \
  -d '{"reset_token": "...", "new_password": "..."}' \
  https://api-dev-app.stella-commerce.com/api/storefront/customer/reset

The recover endpoint returns 202 whether or not the email exists — ghost-account probing is not possible.

Get Started

Authentication

Concepts

Customer Access Token

Get one

Use it

What it permits

Lifetime

Revocation

Account lockout

Recovery flow

​Get one

​Use it

​What it permits

​Lifetime

​Revocation

​Account lockout

​Recovery flow

Get one

Use it

What it permits

Lifetime

Revocation

Account lockout

Recovery flow