Auth & roles

Merchant staff authenticate with Supabase Auth (email/password with session handling). Send the Supabase JWT as a bearer token, plus the x-organization-slug header to pick which of your memberships you're acting on:

curl https://api.litecommerce.io/api/v1/merchant/items \
  -H "Authorization: Bearer <supabase-jwt>" \
  -H "x-organization-slug: your-store"

The guard chain

Three guards run in order on merchant routes:

MerchantAuthGuard — validates the bearer JWT against Supabase Auth and resolves it to a litecommerce user (lazily syncing the user row on first login).
MembershipGuard — reads x-organization-slug and confirms the authenticated user has a membership in that organization. No membership → the request is rejected.
RolesGuard — enforces legacy route-role metadata when present and the newer permission-policy metadata on merchant mutations. Read endpoints are generally open to any member. Writes are open to Owner/Admin by default, and Staff can be delegated specific write capabilities through permission presets or direct permission groups.

Built-in roles

litecommerce ships three base roles:

Role	Typical use
Owner	Full control, including owner-only powers like billing and ownership transfer
Admin	Full operational control across tenant settings, staff, merchandising, and operations
Staff	Read-only baseline; write access comes from permission groups

Staff can hold memberships in multiple tenants and switch between them — useful for agencies and operators who work across brands.

Permission groups

Permission groups are the fine-grained layer below the base role. Owner/Admin members retain broad write access; Staff members start read-only and need one or more groups for merchant mutations:

Group	Controls
`catalog:write`	Products, variants, catalog media, collections, and item ordering
`content:write`	CMS page creation and edits
`inventory:adjust`	Stock adjustments, holds, releases, and low-stock thresholds
`orders:operate`	Order status, fulfillment status, and internal notes
`returns:operate`	Return/RMA status and notes
`reviews:moderate`	Product review approval and rejection
`pricing:write`	Coupons, automatic discounts, sale windows, and bundles
`customers:support`	Customer support workflows
`reports:view`	Reporting and operational analytics
`settings:manage`	Tenant settings and shipping configuration
`team:manage`	Teammate invites and membership management
`api-keys:manage`	Tenant API key create/revoke operations

Future shared-commerce, booking, and subscription surfaces add their own groups as those milestones ship. The built-in permission presets are composed from these groups; custom presets are a tenant-admin workflow.

Additional roles from the pre-permission model map to Staff during migration and should be treated as historical names only.

Public vs. merchant

Public storefront reads need no authentication — they rely on tenant context only. Authentication applies to merchant and platform surfaces, where writes and privileged reads live.

Today, merchant requests authenticate only with a Supabase staff JWT — there's no API-key auth path yet. Epic 2 shipped tenant API-key storage and management (create/rotate/revoke), but the inbound x-api-key auth flow for server-to-server calls lands in a later milestone. See API keys for what exists today vs. what's coming.

Endpoint-level auth and permission requirements are annotated in the API reference.