Authentication

Brainerce has three integration modes, each with its own authentication. Pick the right one before you start.

At a glance

The SDK class is BrainerceClient for all three, and the mode is decided by which key you pass to the constructor:

import { BrainerceClient } from 'brainerce';

If you pass more than one, apiKey wins, then salesChannelId, then storeId. An apiKey puts the client in admin mode regardless of the other two, so never mix an admin key into browser code to "also" read a channel. Passing none throws BrainerceClient: either salesChannelId, apiKey, or storeId is required.

Customer-authenticated actions (order history, profile, saved addresses, submitting a review) also require a Bearer {customerToken} header on top of the mode credential.

Vibe-Coded mode

Used when a vibe-coded site (built with an AI assistant) needs to talk to Brainerce. Identified by a sales channel ID that starts with vc_. Grants storefront-scope access: read products, manage carts, submit orders.

import { BrainerceClient } from 'brainerce';

const client = new BrainerceClient({ salesChannelId: 'vc_abc123xyz' });

The legacy connectionId field is still accepted as a deprecated alias. It logs a deprecation warning on every construction and is kept for backward compatibility; it is not scheduled for removal. Use salesChannelId for new code.

Storefront mode

Used for a public storefront built against a published store. Identified by a storeId.

const client = new BrainerceClient({ storeId: 'store_xyz' });

This mode is not read-only. It is the public storefront surface, and it can write:

• Create and modify carts, apply coupons, link a cart to a customer
• Create a checkout, set the address and shipping method, and complete it, which creates a real order
• Register and log in customers, and run the forgot / reset password flow

What it cannot reach is the admin surface: no product, inventory, pricing, discount, team, or store-configuration writes. Those need an apiKey.

storeId mode has no payment surface. There are no payment routes under /stores/{storeId} at all, and the SDK's payment methods, getPaymentProviders(), createPaymentIntent(), getPaymentStatus(), confirmSdkPayment() and waitForOrder(), all throw BrainerceError 400 ("… is only available in vibe-coded mode") on a storeId client. So storeId mode can reach completeCheckout and mint an order, but it can never collect money for it. Build any real, paying checkout against a salesChannelId. getCategories(), getBrands(), getTags(), getCategoryBySlug(), verifyEmail(), resendVerificationEmail() and the reservation methods (getAvailability(), extendReservation(), releaseReservation()) are sales-channel-only too.

Customer-owned data, meaning profile, order history, saved addresses, and submitting or editing a product review, sits behind a customer JWT on top of the storeId, so a bare storeId client cannot read one shopper's account. Treat the storeId as public (it ships in your client bundle); treat the customer token as a secret.

Admin / API mode

Used for server-side integrations that need full account access. Identified by an API key that starts with brainerce_. Treat the key like a password, and never expose it to a browser or check it into a public repo. The SDK warns on the console if it detects an apiKey in a browser environment.

const client = new BrainerceClient({ apiKey: 'brainerce_live_xyz...' });

When calling the REST API directly (without the SDK), pass the key as a bearer token, because there is no X-Api-Key header:

Authorization: Bearer brainerce_live_xyz...

Create API keys in the dashboard under Account → API Keys.

Customer tokens

Customer-scoped actions (placing an order, viewing order history, updating account) require a JWT customer token issued by Brainerce. Pass it as a Bearer token on top of your mode credential:

Authorization: Bearer {customerToken}

Get a customer token by calling POST /customers/login or POST /customers/oauth/callback. See the Core Integration Guide for the full flow.

Security rules

• Never expose API keys, customer tokens, or webhook secrets to the browser.
• Never send a customer token in a URL. Headers only.
• API keys carry full account permissions. Rotate them if compromised.
• See Critical Rules for the complete security checklist.