Authentication

Tybrite issues two key types per store, so a credential that ships to a browser and a credential that stays on a server are different objects with different powers. Which one a call takes depends on where your code runs and whose data it touches.

API Key Types

We support two distinct key types for every store. You can manage these in your Dashboard under Integrations → API Keys.

Keys issued by a store that runs on a white-label platform carry that platform’s own vendor prefix in place of tybrite_ — acmecommerce_sk_live_…. Only the vendor name changes; the sk/pk and live/test segments are identical everywhere, so parse those rather than matching the full prefix.

Publishable Keys (`tybrite_pk_...`)

Publishable keys are intended for use in frontend applications, such as React websites, mobile apps, or headless storefronts.

Scope: Read-only access to non-sensitive data (Products, Categories, Search).
Security: Safe to include in client-side bundles or public repositories.

Usage:

const client = new Tybrite({ apiKey: 'tybrite_pk_live_...' });

Secret Keys (`tybrite_sk_...`)

Secret keys are for server-side environments and provide full administrative access to your commerce data.

Scope: Full Read/Write access (Orders, Customers, Payments, Settings).
Security: Must never be exposed to the client. Keep them in environment variables (TYBRITE_SECRET_KEY).

Usage:

const client = new Tybrite({ apiKey: process.env.TYBRITE_SECRET_KEY });

Environments & Sandbox

The key prefix determines which environment your requests target — there is no separate sandbox base URL.

Prefix	Environment	Data scope
`tybrite_sk_live_` / `tybrite_pk_live_`	Production	Live customer, order, and inventory data
`tybrite_sk_test_` / `tybrite_pk_test_`	Sandbox	Isolated test data — never mixed with production

What sandbox isolation means in practice:

Orders, customers, cart items, wishlist entries, product reviews, and messaging conversations created with a test key are stored in the sandbox partition and are never returned to live key requests.
Payment providers switch to test mode automatically when a test key is used — Stripe test mode, PayPal sandbox, Paystack test keys, M-Pesa sandbox — regardless of what your store’s payment settings show.
Every authenticated response includes a Tybrite-Environment: production | sandbox header so you can confirm which partition resolved.

Build and test your entire integration with tybrite_sk_test_* keys. When you’re ready for production, swap to tybrite_sk_live_* and the right environment follows automatically — no code changes needed.

Authorization Header

For direct REST API calls, provide your key in the Authorization header using the Bearer scheme:

Authorization: Bearer tybrite_sk_live_YOUR_KEY

Advanced Security: HMAC Signing

Sensitive operations — order creation, payment initialization — carry a request signature in addition to the key, so a tampered body or a replayed request is rejected rather than acted on.

Generating the signature

The signature is a SHA-256 HMAC hash of the payload, where the payload is the current Unix timestamp concatenated with the JSON request body.

import { createHmac } from 'crypto';

// 1. Prepare Payload
const timestamp = Math.floor(Date.now() / 1000);
const body = JSON.stringify(requestData);
const payload = `${timestamp}.${body}`;

// 2. Generate Signature
const signature = createHmac('sha256', process.env.TYBRITE_HMAC_SECRET)
  .update(payload)
  .digest('base64');

// 3. Include in your request:
// xTimestamp: timestamp
// xSignature: signature

The timestamp may be sent in seconds or milliseconds — both are accepted — and a signature is valid for five minutes either side of it. Sign the exact bytes you send: re-serializing the body after signing it produces a different string and the signature will not match. Endpoints requiring HMAC signing:

Endpoint	Requirement
`POST /v1/orders`	Required
`PATCH /v1/orders/:id`	Required
`POST /v1/payments/initialize`	Required
`POST /v1/b2b/orders`	Required by default; a store can relax it in its B2B settings
`POST /v1/ingest/products`	Always required, with no opt-out, in addition to a secret key

Most integrations sign with the store’s own signing secret, shown above as TYBRITE_HMAC_SECRET. An application that connected through GC Connect instead receives its own per-merchant signing_secret at the code exchange and signs with that.

Idempotency Protection

State-changing financial operations require an Idempotency-Key header, so a retry after a network failure resolves to the original charge or order rather than a second one.

Mechanism: The server tracks these keys. If a request is retried with the same key, the server returns the original response with an idempotent: true flag.
Choosing a key: A unique UUID, or a hash of the transaction details (e.g., payment-order_123-ts_456).

Endpoints requiring an Idempotency Key:

POST /v1/payments/initialize
POST /v1/orders
PATCH /v1/orders/:id

Customer Session Tokens (`xAuthToken`)

While API keys authenticate your application to Galactic Core, customer session tokens authenticate end customers to their own data within your store. They are required on top of an API key for endpoints that access or modify a specific customer’s records (cart, wishlist, profile, gift cards, messaging). The two credentials are independent, so a leaked publishable key on its own reaches no specific customer’s data: that also requires the customer’s JWT, which only the AuthenticationService issues, and only after a successful login, OTP verification, or magic-link redemption.

Affected endpoints

Endpoint	`xAuthToken` requirement
`GET` / `PATCH /v1/customers/{id}`	Required. Token’s subject must match path `id`.
`GET` / `POST` / `PATCH` / `DELETE /v1/cart/*`	Required when `customer_id` is supplied (anonymous session carts omit it).
`GET` / `POST` / `DELETE /v1/wishlist/*`	Required — wishlist always requires `customer_id`.
`GET /v1/gift-cards?customer_id=...`	Required when `customer_id` is supplied.
`GET` / `POST` / `PATCH /v1/messaging/*`	Required, gated by thread or message ownership.

Example flow

// 1. Customer logs in — mint the session JWT
const { customer, session } = await client.authentication.login({
  requestBody: { email: 'user@example.com', password: '...' }
});

const token = session.access_token;

// 2. Pass it on every customer-scoped call
await client.cartWishlist.addToCart({
  xAuthToken: token,
  requestBody: { customer_id: customer.id, product_id: 'prod_123', quantity: 1 }
});

await client.customers.getCustomer({
  xAuthToken: token,
  id: customer.id
});

// 3. Refresh before expiry (~1 hour)
const { session: fresh } = await client.authentication.refreshToken({
  requestBody: { refresh_token: session.refresh_token }
});

Recommended storage: prefer httpOnly, Secure, SameSite=Lax cookies over localStorage. Cookies are immune to XSS-based token theft and the browser handles attachment automatically. Reach for localStorage only when your storefront is a native mobile WebView or a same-origin SPA without a backing server, and pair it with a strict CSP.

Never log, persist server-side, or share customer access tokens between sessions. Each token is bound to a single customer and grants direct read/write access to their cart, wishlist, profile, and messages.

Key Usage by Endpoint

Every endpoint accepts one of the credentials above, or a combination of them. The legend:

pk or sk — either a publishable or a secret key works.
sk only — a secret key is required; a publishable key returns 403 Forbidden.
pk (browser) — a publishable key is enough; safe to call directly from the browser.
+ session — also requires a customer session token: xAuthToken, or one of the bring-your-own-auth credentials (x-external-auth for a signed assertion, x-idp-token for a token from your own identity provider). Send exactly one of the three.
+ HMAC — also requires a request signature.
Public — no key required.
Operator — a marketplace operator key (marketplace deployments only).

Discovery & catalog (read)

Endpoints	Key
Products, collections, specifications (`client.products.*`)	`pk` or `sk`
Categories & subcategories (`client.taxonomy.*`)	`pk` or `sk`
Prices (`client.pricing.*`)	`pk` or `sk`
Search — text & semantic (`client.search.*`)	`pk` or `sk`
Tax preview (`client.tax.previewTax`)	`pk` or `sk` (browser)
Recommendations (`client.recommendations.*`)	`sk` only
Discovery — most-viewed / most-added-to-cart / best-converting (`client.discovery.*`)	`pk` or `sk` (browser)
Event capture (`client.events.recordEvent`)	`pk` (browser)
Blog posts & lookbooks (`client.cms.*`)	`pk` or `sk`
Store info (`client.system.getStoreInfo`)	`pk` or `sk`
API info `/`, health `/v1/health`	Public
Public catalog feed `/v1/feeds/{store}/products.json\|xml`	Public (per-store opt-in)

Cart & wishlist (storefront writes)

Endpoints	Key
Cart read/write (`client.cartWishlist` cart methods)	`pk` (browser) — anonymous via session id; + session when a `customer_id` is supplied
Cart merge (`mergeCart`)	`pk` (browser) + session
Wishlist (`getWishlist`, `addToWishlist`, …)	`pk` (browser) + session

Customers & authentication

Endpoints	Key
Auth — register / login / logout / magic-link / verify-otp / reset / refresh / me (`client.authentication.*`)	`sk` only
Create customer (`client.customers.createCustomer`)	`sk` only
Customer self — profile & addresses (`getCustomer`, `updateCustomer`, address methods)	`pk` (browser) + session

Checkout — orders & payments

Endpoints	Key
List / get orders (`client.orders.listOrders`, `getOrder`)	`sk` only
Create / update order (`createOrder`, `updateOrder`)	`sk` only + HMAC (idempotency key required on create)
Payment methods (`client.payments.getPaymentMethods`)	`pk` or `sk`
Initialize payment (`initializePayment`)	`sk` only + HMAC (idempotency key required)
Verify payment (`verifyPayment`)	`sk` only

Engagement

Endpoints	Key
List reviews (`client.reviews.listReviews`)	`pk` or `sk` (publishable sees approved only)
Submit / delete own review, mark helpful	`pk` (browser) + session (helpful vote needs no session)
Returns — lodge / list / track / accept-credit / request-refund (`client.returns.*`)	`pk` (browser) + session (`listReturnReasons` needs no session)
Messaging — threads, messages, realtime token (`client.messaging.*`)	`pk` (browser) + session
Gift card check by code (`checkGiftCard`)	`pk` or `sk`
List my gift cards (`listGiftCards`)	`pk` (browser) + session
Promotions — list & calculate (`client.promotions.*`)	`pk` or `sk`
Shipping — zones, calculate, track (`getShippingZones`, `calculateShipping`, `trackShipment`)	`pk` or `sk`

Platform & integrations

Endpoints	Key
Webhook endpoints & events (`client.webhooks.*`)	`sk` only
Catalog ingestion — push (`client.ingestion.ingestProducts`)	`sk` only + HMAC (idempotency key required)
Ingestion sample / dry-run test (`getIngestSample`, `testIngest`)	`sk` only
Connect — authorize validate, token, revoke (`client.gcConnect.*`)	Public (OAuth-style client credentials)
Connect — list sessions (`listConnectSessions`)	`sk` only
Sandbox tools — reset / time-travel / webhook replay (`client.sandbox.*`)	*`sk` test* key only** (`tybrite_sk_test_*`; sandbox env)

Marketplace (operator deployments)

Endpoints	Key
Unified split checkout (`/v1/cart/checkout`)	Operator
Unified shopper profile (`client.marketplace.getMarketplaceCustomer`)	Operator + `X-Customer-Token`
Marketplace info (`client.marketplace.getMarketplaceInfo`)	Operator
Any discovery endpoint with an operator key	Operator (aggregates across merchants; narrow with `storeId`)

Session Management

When building authenticated customer experiences (like “My Account” or “Quick Checkout”), the Tybrite SDK handles session persistence via xAuthToken.

Login: Call client.authentication.login() to receive a session and user object.
Persistence: Store the session.access_token securely (httpOnly cookies preferred).
Requests: Provide the token via the xAuthToken SDK parameter (or x-auth-token header for raw REST) on protected endpoints.
Refresh: Call client.authentication.refreshToken() ~60s before expires_at to rotate to a fresh session.

Our TypeScript SDK exposes refreshToken so you can wire up a scheduled rotation. See the Authentication Service for the full method reference and lifecycle diagram.

Introduction

How GC Works

Build with AI

Extend the platform

Commerce capabilities

Distribute

Native Integrations

Resources

API Key Types

Publishable Keys (`tybrite_pk_...`)

Secret Keys (`tybrite_sk_...`)

Environments & Sandbox

Authorization Header

Advanced Security: HMAC Signing

Generating the signature

Idempotency Protection

Customer Session Tokens (`xAuthToken`)

Affected endpoints

Example flow

Key Usage by Endpoint

Discovery & catalog (read)

Cart & wishlist (storefront writes)

Customers & authentication

Checkout — orders & payments

Engagement

Platform & integrations

Marketplace (operator deployments)

Session Management

​API Key Types

​Publishable Keys (tybrite_pk_...)

​Secret Keys (tybrite_sk_...)

​Environments & Sandbox

​Authorization Header

​Advanced Security: HMAC Signing

​Generating the signature

​Idempotency Protection

​Customer Session Tokens (xAuthToken)

​Affected endpoints

​Example flow

​Key Usage by Endpoint

​Discovery & catalog (read)

​Cart & wishlist (storefront writes)

​Customers & authentication

​Checkout — orders & payments

​Engagement

​Platform & integrations

​Marketplace (operator deployments)

​Session Management

API Key Types

Publishable Keys (`tybrite_pk_...`)

Secret Keys (`tybrite_sk_...`)

Environments & Sandbox

Authorization Header

Advanced Security: HMAC Signing

Generating the signature

Idempotency Protection

Customer Session Tokens (`xAuthToken`)

Affected endpoints

Example flow

Key Usage by Endpoint

Discovery & catalog (read)

Cart & wishlist (storefront writes)

Customers & authentication

Checkout — orders & payments

Engagement

Platform & integrations

Marketplace (operator deployments)

Session Management