Authentication

Learn how to secure your Tybrite commerce integrations using API keys and HMAC signing.

Tybrite uses a dual-key architecture to ensure maximum security without sacrificing developer experience. Depending on where your code runs, you will use different keys and authentication patterns.

API Key Types

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

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 });
  

---

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, such as order creation or payment initialization, require an additional layer of security to prevent request tampering and replay attacks. For these requests, you must provide verified headers.

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

Endpoints requiring HMAC signing:

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

---

🔄 Idempotency Protection

To prevent duplicate charges and orders—especially during network retries—all state-changing financial operations require a mandatory Idempotency-Key header.

• 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.
• Best Practice: Generate 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).

Why both? A leaked publishable key alone gives an attacker no way to read or modify any specific customer’s data — they would also need that customer’s JWT, which only the AuthenticationService can issue, and only after a successful login / OTP verification / 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.auth.login({
  requestBody: { email: '[e-mail]', 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.auth.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.

---

Session Management

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

1. Login: Call client.auth.login() to receive a session and user object.
2. Persistence: Store the session.access_token securely (httpOnly cookies preferred).
3. Requests: Provide the token via the xAuthToken SDK parameter (or x-auth-token header for raw REST) on protected endpoints.
4. Refresh: Call client.auth.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.