Skip to main content

Keys and security

A storefront built with the Storefront SDK calls the GraphQL API with API keys. This page covers which keys a storefront needs, where each one goes and what to check before the storefront goes live. It applies to every approach: a scaffolded boilerplate and your own app alike.

Checked against create-propeller-shop 0.11.2, the boilerplates of 18 October 2026 and @propeller-commerce/propeller-sdk-v2 0.18.0.

The two keys​

You create API keys in the Backoffice (see Environments and access). A storefront uses two:

KeyWhat the storefront uses it forWhat it may do
API keyEvery catalog, cart, checkout and account callOnly what a storefront needs
Order-editor API keyOrder actions the storefront key may not run: setting the order status after a payment, sending a password reset link, sending the quote request and order confirmation emails, reading a just-placed order. With PunchOut, also reading the buyer Contact's shared secret and creating its sign-in tokenOnly these actions

Never use an admin key in a storefront. The storefront's GraphQL route adds its key to the requests that visitors' browsers send, so whatever the storefront's keys may do, a visitor can do too. Keys limited to the storefront's own work keep that harmless.

How the GraphQL route uses the keys​

The browser never calls Propeller directly. It posts every GraphQL request to the storefront's own route, /api/graphql, which runs on the server:

Browser                       /api/graphql (your server)          Propeller GraphQL API
───────                       ──────────────────────────          ─────────────────────
POST /api/graphql       →     adds the API key
                              and the user's access token   →     answers with data
                        ←     passes the response back      ←

The SDK client posts to this route in its default proxy mode, and it sends no key itself. When a user signs in, the route forwards their access token with each request, so the API answers with their prices and their data.

The keys live in server-only settings:

StackAPI keyOrder-editor API key
Next.jsBOILERPLATE_API_KEYBOILERPLATE_ORDER_EDITOR_API_KEY
NuxtBOILERPLATE_API_KEYBOILERPLATE_ORDER_EDITOR_API_KEY
VueSSR_API_KEYSSR_ORDER_EDITOR_API_KEY

In your own app you write this route yourself. Add the SDK to your app shows a minimal one. Keep the order-editor key out of it: run order actions, such as the status update after a payment, in your own server code. The payment providers work that way.

Before you deploy​

  • Keys. Use the two keys above, limited as described, and set them in your host's secret store. Never an admin key.
  • The behavior dashboard. The boilerplates include a dashboard at /tracker that shows the activity and revenue of every Company that uses the shop, with its data endpoint at /api/tracker. Put both behind your own sign-in check before you deploy, or remove them.
  • The refresh endpoint. Set REVALIDATE_SECRET to a long random value. The endpoint refuses requests without a matching X-Revalidate-Secret header. See Routing.
  • Payments. Payment provider keys stay on the server, and the webhook needs a public URL. See Payment providers.

See also​

Last updated on