Tokens

Three different things in theme work are called "tokens". They have nothing in common except the word.

Design tokens (theme.config)

Design tokens are not secrets. They are the named design values of your theme, and each one becomes a CSS variable: colors.primary is var(--colors-primary).

// theme.config.ts
tokens: {
  colors: { primary: '#111111', background: '#ffffff' },
  fonts: { body: 'system-ui' },
},
overridable: ['colors.primary', 'colors.background'],

• Can: set every colour, font, spacing, shadow and radius your CSS uses; give a light and a dark set; let a store owner's brand settings or a style change the tokens listed in overridable.
• Cannot: carry any access. They are plain values, bundled into the theme and visible to every shopper.
• Create / change: edit theme.config.ts and rebuild. Rotate / revoke: not applicable.
• Never: put anything private in them (they ship to the browser), or list layout tokens (spacing, radii, shadows) in overridable, where a brand setting could break your layout.

The full rules are in theme-config.md.

Developer tokens (BIZZPOCKET_DEV_TOKEN)

A developer token lets the developer of a store's theme run bizzpocket dev --store <slug> and preview the theme on their own computer against that store's real data.

export BIZZPOCKET_DEV_TOKEN=bpdt_...
bunx bizzpocket whoami --store my-store    # which store, and when it expires
bunx bizzpocket dev --store my-store

What it can do

• Read the public storefront data of one store, the one it was made for: products, product details, search, categories, menus, the store profile, the home page settings, promotions, and the theme's pages. That is the same data any shopper sees on the live store.
• Exactly these storefront operations: productGridProducts, productSearch, productDetail, productSuggestions, productFrames, categoryTree, categoryTreeWithFeatured, categoryFilters, navigationMenu, storeProfile, storeHome, storePromotions, gemCertificate (the browser-query set) and the page endpoint that dev renders through.

What it cannot do

• Read any other store. The store comes from the token, never from the request: asking for another store's page, or naming another store in a query, is refused (403).
• See customers, orders, carts, checkout, wishlists, or anything in the seller or admin dashboards. Those operations are refused (403), and the token never counts as a signed-in shopper.
• Change anything. Every allowed operation is a read.
• See unpublished drafts. Preview links are ignored with a developer token.
• Run more than 120 requests a minute (the page endpoint and GraphQL together). Past that: 429.

A token that is unknown, revoked or expired gets a bare 401, with no hint which. whoami turns that into a plain message.

Where it lives. In your shell's environment, nowhere else. BizzPocket stores only a SHA-256 hash of it, so nobody, including the store owner, can see it again after it is created. The CLI sends it only to the --api host (https://api.dev.bizzpocket.com by default), only over https (plain http only to localhost), in the x-bp-dev-token header. It never prints it.

Create (store owner): seller dashboard → Settings → Developers → New token. Give it a name (who it is for) and an expiry: 7, 30 or 90 days (the default) or 1 year. The token is shown once, with a copy button. A store can have 10 active tokens.

Rotate: create a new token, send it to the developer, then revoke the old one. Do this when a developer stops working on the theme, when a token may have leaked, and before it expires.

Revoke (store owner): Settings → Developers → Revoke next to the token, then confirm. It stops working at once. The list shows when each token was created, last used (to the minute) and when it expires, so an unused or unexpected token is easy to spot.

Never

• put it in a file in the theme folder: not in theme.config.ts, not in a .env, not in a script;
• commit it, paste it in an issue, a chat channel or a screenshot, or print it in a log;
• share one token between developers (make one each, so you can revoke one without the other);
• point --api at a host you do not trust, or run a theme you do not trust with the token in your shell (the theme's code runs in the same process).

The team's internal token. BizzPocket team members can still put the dev environment's internal API token in BIZZPOCKET_DEV_TOKEN. dev tells the two apart by the bpdt_ prefix and sends the internal token as x-internal-token, as before. It is not scoped to a store: never give it to anyone outside the team.

Registry token (.npmrc)

The registry token lets your package manager and bizzpocket add / diff download @bizzpocket/* packages from npm.bizzpocket.com when your access needs one.

# .npmrc (in the theme folder or your home folder)
@bizzpocket:registry=https://npm.bizzpocket.com
//npm.bizzpocket.com/:_authToken=${NPM_TOKEN}

export NPM_TOKEN=...

• Can: download packages from the registry it was issued for (and publish, if your registry account may publish).
• Cannot: read any store's data, or do anything on BizzPocket itself.
• Where it lives: your shell, as NPM_TOKEN (or BIZZPOCKET_NPM_TOKEN / VERDACCIO_TOKEN). The .npmrc only names the variable; any other ${NAME} there is refused. The CLI sends it only to npm.bizzpocket.com and hosts you name with --trust-registry, only over https, and withholds it while a proxy or custom CA variable is set.
• Create / rotate / revoke: through whoever runs your registry (for npm.bizzpocket.com, your BizzPocket contact). After a rotation, update the variable in your shell and in CI secrets.
• Never: write the token itself into .npmrc (only ${NPM_TOKEN}), commit an .npmrc that holds one, or add --trust-registry for a host you do not control.

The full rules are in registry.md.