Skip to content
cartonium docs

API keys

Storefront requests also carry their current origin: browsers supply Origin; SSR and backend transports forward x-storefront-origin. Domains selects Live or Sandbox data automatically, including token-only calls. Missing or conflicting context is rejected, with no Live fallback. See storefront data selection.

Tenant API keys authenticate server-to-server calls from an external / BYO storefront's backend — a server talking to cartonium without a logged-in staff member. They are server-side only: the secret is a bearer credential and must never appear in browser JavaScript, a storefront client bundle, or a public env var. Anonymous catalog reads use /public/* with tenant context; customer account features use their separate customer-session contract. See Tenants & context and Customer accounts & sign-in.

Staging implementation. Inbound x-api-key authentication is implemented for the external-storefront server-to-server surface (/api/v1/storefront/*), including storefront context and catalog reads for items and collections. Full API-key productization remains in active development; this staging contract does not establish Production availability. Merchant routes still use the Supabase staff JWT. See Auth & roles, environments, and What's still coming.

How it works

  • Key storage + management — a public key plus a hashed secret, with scopes, a lastUsedAt timestamp, and no expiry by default. Creation accepts a name and scopes, with no caller-set expiry; a key with a past expiresAt is rejected like a revoked key. Merchant APIs already provide create/list/revoke; create and revoke require key-management permission. Rotate by issuing a replacement, deploying it, then revoking the old key. Keys are tenant-scoped.
  • Inbound x-api-key auth — a verification guard resolves the key, enforces the route's scopes, records lastUsedAt, and rate-limits per key. The tenant is resolved from the key itself (no spoofable slug header) and must match the tenant and mode selected by the current storefront origin.

Authenticating

Send the key — the publicKey joined to its secret with a single . — as the x-api-key header:

x-api-key: <publicKey>.<secret>     # e.g. lcp_….lck_…

The publicKey (safe to log) identifies the key; the secret is verified server-side. The secret is shown once at creation — store it where only your server can read it, never in client code. Keys are server-side only.

Scopes

The storefront catalog routes below require storefront:read. The related scope names have different availability:

  • storefront:read — reads a tenant's storefront catalog/context in the staging implementation.
  • checkout:write — reserved for the conditional server-to-server checkout bridge. Holding this scope does not make a checkout route available; use the documented BYO checkout API for current checkout integrations.

A request to these reads whose key lacks the required scope is rejected with 403 and the error code API_KEY_SCOPE_INSUFFICIENT; the response details.missingScopes array names exactly which scopes to add.

Server-to-server storefront reads

Use x-api-key only from your storefront backend. The tenant comes from the key, so these routes do not use x-organization-slug:

  • GET /api/v1/storefront/context
  • GET /api/v1/storefront/items
  • GET /api/v1/storefront/items/search
  • GET /api/v1/storefront/items/{slug}
  • GET /api/v1/storefront/collections
  • GET /api/v1/storefront/collections/{slug}
  • GET /api/v1/storefront/collections/{slug}/items

Catalog responses reuse the same public-safe item and collection projections as the browser /public/* catalog routes and only return active, non-archived catalog records. The optional server-to-server checkout bridge is tracked separately and should not be assumed live.

What's still coming

Full self-serve productization belongs to E6: API & Developer Platform, currently scheduled in M8 (GitHub milestone #8), and has not shipped: the merchant self-service key-management UI, SDKs / generated clients, a public developer portal, a rich scope editor, and usage analytics/billing. Existing key-management APIs and operator-assisted issuance are separate from that unfinished UI/productization work. This guide covers the server-to-server catalog family above; use the API reference for other scope-specific contracts and their availability. Don't present API keys as a full self-serve product yet.

Tenant outbound webhooks are a separate E17: Tenant Webhooks & Event Delivery boundary and are not currently scheduled. API-key delivery does not imply that an outbound event-delivery contract is available.

Related