Auth & roles

Merchant staff authenticate with Supabase Auth. Send the Supabase access JWT as a bearer token, plus x-organization-slug on tenant-scoped operations to pick which of your memberships you're acting on. Customer accounts use a separate opaque session, described below.

This example uses the Preview API and an enabled tenant Sandbox. Confirm your environment and commerce mode before making calls:

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

The guard chain

Tenant-scoped merchant mutations normally use this guard chain:

MerchantAuthGuard — validates the bearer JWT against Supabase Auth and resolves it to a cartonium 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. A missing or unknown slug, or no membership, returns the same 403 rejection.
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.

Requirements vary by operation. For example, GET /api/v1/merchant/auth/session needs the staff JWT but no tenant header: it returns the caller's memberships before a tenant is selected. Some reads use the authentication and membership guards without a role policy. Check the API reference for the operation you call.

Built-in roles

cartonium 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 operations, 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
`shared-commerce:quotes`	Quote creation, revisions, delivery, acceptance, and voiding
`shared-commerce:invoices`	Invoice creation, collection, delivery, and voiding
`shared-commerce:contracts`	Contract preparation, delivery, countersigning, and signature management
`shared-commerce:manual-payments`	Recording non-card payments and payment corrections
`bookings:operate`	Booking setup, capacity preflight, assignments, and lifecycle mutations
`bookings:override`	High-risk controlled-shortage actions; also requires `bookings:operate`
`subscriptions:operate`	Subscription plans, customer subscriptions, renewals, pauses, and cancellations
`subscriptions:override`	High-risk subscription price and lifecycle overrides
`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

Shared-commerce, booking, and subscription surfaces use these groups in the same model. 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.

Choose the credential for the operation

Surface	Credential and tenant context
Anonymous public catalog/content	No credential; `x-organization-slug` selects the tenant
Tenant-scoped merchant operations	Supabase staff JWT plus `x-organization-slug`; membership and the operation's permission policy apply
Customer account operations	Opaque `CustomerSession`, separate from Supabase Auth, plus `x-organization-slug`
Emailed customer action links	The purpose-bound action token plus `x-organization-slug`; no customer session is required
Checkout payment handoff	The checkout token resolves the session and tenant; this operation does not require `x-organization-slug`
Server-to-server storefront reads (staging implementation)	Server-side only `x-api-key`; the tenant comes from the key

For BYO customer accounts, keep the opaque session bearer on your backend and proxy customer calls; never substitute a merchant JWT or expose the session to browser JavaScript. Hosted cartonium checkout provides its own account UI and server-side session forwarding. See Customer accounts & sign-in.

Inbound API-key authentication is implemented on staging for the separate /api/v1/storefront/* surface. Full self-serve productization remains in active development; a staging contract is not a Production availability claim. Keys do not replace staff JWTs on merchant routes. See API keys for the server-side contract and remaining work.

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