Skip to main content

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.

Stella is multi-tenant by construction. Every row in every table is tagged with a site_id (or transitively, via a foreign key to a row that is). Every query in every endpoint filters by site_id drawn from the caller’s token. There is no code path that elides this filter.

​
Where site_id comes from

CallerSource
Storefront tokenstorefront_access_tokens.merchant_id (joined to merchants.site_id)
Customer tokenThe customer’s merchant_id at the time the token was minted
Agent tokenThe agent’s merchant_id (inherited from the customer who consented)
DashboardThe authenticated user’s active merchant (per session)
Calls cannot cross merchants. A customer token from kasa returns 401 on /api/storefront/products if X-Site-ID: huba-nepal is sent — because the storefront-token gate runs first and rejects the mismatch.

​
Data isolation invariants

  1. Every multi-tenant table has a site_id column or a non-nullable FK to one that does. Reviewed at PR time; integration tests assert.
  2. Every query joins through site_id or filters on it. SQLAlchemy model definitions encode the relationships; cross-tenant joins would require explicit ORM gymnastics.
  3. Every webhook payload carries site_id so consumers can route without ambiguity.
  4. Audit events include merchant_id for cross-merchant forensics.

​
Per-merchant CORS

/api/storefront/* does dynamic CORS reflection: the response Access-Control-Allow-Origin only mirrors the request’s Origin if it appears in any active token’s allowed_origins for the merchant identified by X-Site-ID. Tokens revoked or merchants without an allowlisted origin → preflight 403. This is enforced on top of standard server-side Origin checks — both layers must pass.

​
Multi-merchant developer use cases

If you operate multiple Stella tenants (e.g. an agency managing several brands), you mint one storefront token per tenant. Tokens don’t compose across merchants; each call carries exactly one X-Site-ID and one X-Stella-Token.