> ## Documentation Index
> Fetch the complete documentation index at: https://docs.joinmarkt.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> Sessions, public routes, checkout tokens, and webhook signatures.

Join Markt does not issue long-lived Bearer API keys for a public admin REST surface. Auth depends on which surface you call.

## Public (no seller session)

These routes intentionally omit `requireSession`:

* `POST /api/embed/checkout` (CORS `*`)
* `GET /api/stores/by-subdomain/{subdomain}/storefront`
* `GET /api/stores/by-subdomain/{subdomain}/products`
* `GET /api/store/{subdomain}`
* `POST /api/checkout/start`
* `POST /api/coupons/validate`
* `POST /api/track`
* Most payment **create** / **verify** paths used by checkout UI

Authorization still exists: products must be purchasable, stores must not be banned, amounts must match DB orders, and rate limits apply.

## Seller / staff session

Dashboard APIs use the Join Markt session cookie established by `/api/auth/login`. Guards:

* `requireSession(req)` — logged-in user + CSRF when cookie session is used
* Store-scoped permissions (`viewOrders`, `manageCoupons`, `manageSettings`, `manageTickets`, …)

Example: domain assign/verify requires `manageSettings` on `{storeId}`.

## Checkout access tokens

Buyer-facing order endpoints accept a checkout token (query / cookie via `/api/checkout/enter` and `/api/checkout/session`) or legacy email match. Staff with `viewOrders` can also read delivery payloads.

## Customer session

`/api/customer/*` and parts of `/api/v1/customer-dashboard/*` use **customer** sessions — separate from seller login.

## Payment webhooks

Inbound webhooks authenticate with **gateway signatures** (Stripe signing secret, Cryptomus sign, etc.). They are CSRF-exempt by design. Treat webhook secrets like production credentials.

## CSRF policy

Cookie CSRF is enforced inside session/admin guards (`lib/api/csrf-policy.ts` lists exempt prefixes for auth bootstrap, payments, embed-adjacent checkout, `/api/v1/*`, etc.). Public CORS embed POST does not send a seller CSRF token.

## Practical guidance

| You are building…             | Use                                                                  |
| ----------------------------- | -------------------------------------------------------------------- |
| Buy button on a merchant site | Embed SDK (public)                                                   |
| Custom theme checkout         | `checkout/start` same-origin                                         |
| Seller automation             | Session from your own backend (or wait for a future API-key product) |
| Settlement listener           | Gateway webhook endpoint                                             |

Never put a seller session cookie into a third-party storefront.