Resource locations

The Brainerce API spreads across three URL shapes. All accept an API key (Authorization: Bearer brainerce_*); they differ in stability guarantee.

All three use the same auth (API key + scopes), the same rate limits, and the same error format. Only /api/v1/* carries the versioning guarantee.

When in doubt: use /v1/*. It is the only surface with a stability promise, and it now covers most of what integrations need. Reach for the other two only for the rows below that have no /v1/* equivalent.

Full resource map

The two surfaces use two different scope vocabularies. /v1/* routes declare their scope directly (regions:read, tax-classes:write, reviews:write, …). Everything below the divider is gated by a store permission that is then mapped to a scope — which is why store settings needs settings:write rather than a store-settings:* scope that does not exist, and why bundle offers and order bumps ride on products:* rather than a marketing:* scope that does not exist either. If a call 403s with INSUFFICIENT_SCOPE, the message names the scopes it would have accepted — add one of those.

Storefront vs admin in the same resource

Some resources (products, reviews, customer auth) have both:

• Storefront read — /api/vc/{salesChannelId}/products — public, no API key needed. Returns published items only.
• Admin read/write — /v1/products — requires products:read/products:write scope on an API key.

The storefront namespace is what create-brainerce-store wires by default. The admin namespace is what scripts and back-office systems use. Both can coexist in the same integration:

// public storefront — no key
const storefront = new BrainerceClient({ salesChannelId: 'vc_xxx' });
const { data: published } = await storefront.getProducts();

// admin — same store, and you can ask for drafts
const admin = new BrainerceClient({ apiKey: 'brainerce_xxx' });
const { data: drafts } = await admin.getProducts({ status: 'draft' });

The SDK method is getProducts(), not listProducts(), and the draft filter is status: 'active' | 'draft' — there is no includeDrafts option.

Picking the right scope

Scopes follow {resource}:read and {resource}:write consistently. When you create an API key at Settings → Authentication → API Keys, pick the minimum scope set the integration needs. Common combinations:

*:read is not a scope

Only three shapes match at authorization time:

• an exact string — products:read
• a resource wildcard — products:*, which matches products:read and products:write
• the literal * — which cannot be minted; key creation rejects it

There is no *:<action> form. A key holding *:read matches nothing at all, and every call it makes fails with 403 INSUFFICIENT_SCOPE — the failure looks like a permissions bug rather than a typo, which is why it is worth naming here. Enumerate the scopes, or use {resource}:* per resource.

One further catch: the resource wildcard is honoured on /v1/* routes only. The store-scoped and top-level dashboard routes below the divider compare scope strings exactly, so products:* does not open /bundle-offers there — list products:read and products:write explicitly if the key needs both surfaces.

Related

• Authentication — the full auth flow per mode
• Rate limits — tiered limits per key
• Versioning — what counts as a breaking change in /v1/*
• Webhooks — subscribe, verify signatures, read deliveries
• Public API (v1) reference — every /v1/* endpoint