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

# Customer Access Token

> The per-customer token returned on login.

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

```bash theme={null}
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
```

```json theme={null}
{
  "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.

```bash theme={null}
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

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