GC Connect

GC Connect — Connect your GC Store — is a hosted authorization flow (“Login with GC”) for third-party tools. Instead of asking a merchant to find and paste an API key, you send them to a Tybrite-hosted consent screen; they approve the permissions you asked for, and your server receives a key pair (sk + pk) scoped to that merchant’s store. The keys are permanent — they stay active until the merchant disconnects your app or you revoke them.

Approval required. Your application must be approved by Galactic Core before the Connect flow will work. Apply via the Developer Portal to receive your client_id, client_secret, and registered redirect URIs.

When to use it

Use GC Connect when you’re building a tool that acts on behalf of other merchants — an app, a SaaS integration, an agency dashboard — and you want them to onboard in one click:

A marketing or analytics tool that needs read access to a merchant’s catalog and orders.
A fulfillment or ERP integration that creates and updates orders for many stores.
Any product where each customer is a different Tybrite merchant and you don’t want to handle their keys manually.

If you’re building your own storefront against your own store, you don’t need Connect — just use the API key from your dashboard.

The flow

GC Connect is a five-step, redirect-based handshake. The merchant’s browser carries them through the consent screen; your server does the final code-for-keys exchange.

Redirect to the consent screen

Send the merchant’s browser to the hosted consent page with your client_id, redirect_uri, the scope you need, and a random state value (which you store to verify later).

Merchant approves

The merchant logs in (if they aren’t already) and reviews exactly which permissions and which store they’re granting. They click Authorize.

Redirect back with a code

Galactic Core redirects the browser back to your redirect_uri with a short-lived, single-use code and your original state.

Exchange the code (server-side)

Your server calls connectToken with the code plus your client_id and client_secret. You get back the merchant’s sk, their pk, and a signing_secret for signing write requests.

Store the credentials securely

Save the sk and the signing_secret server-side — both are shown only once. The sk authenticates every call you make for that merchant; the signing_secret signs the write requests that require a signature. The pk is safe for browser/mobile read operations.

Quick start

Build the authorization URL and redirect the merchant’s browser to it. Generate a random state and stash it in the user’s session — you’ll check it against the value that comes back to defend against CSRF.

const state = crypto.randomUUID();
req.session.gcConnectState = state; // store to verify on callback

const params = new URLSearchParams({
  client_id: process.env.GC_CLIENT_ID!,
  redirect_uri: 'https://yourapp.com/callback',
  scope: 'read orders:read customers:read',
  state,
  environment: 'production', // or 'sandbox' while developing
});

res.redirect(`https://gc.tybritelabs.com/connect/authorize?${params}`);

2. Handle the callback and exchange the code

When the merchant approves, their browser lands back on your redirect_uri with ?code=…&state=…. Verify the state, then exchange the code for keys from your server — never from a browser, because it requires your client_secret.

import { Tybrite } from '@tybrite-labs/sdk';

// The authorize/token exchange uses your client_id + client_secret (below) — no store key yet.
const client = new Tybrite();

// GET /callback?code=XXX&state=YYY
async function handleCallback(req, res) {
  const { code, state } = req.query;

  // Always verify state first — this prevents CSRF
  if (state !== req.session.gcConnectState) {
    return res.status(400).send('State mismatch — possible CSRF');
  }

  const keys = await client.gcConnect.connectToken({
    requestBody: {
      code,
      client_id: process.env.GC_CLIENT_ID!,
      client_secret: process.env.GC_CLIENT_SECRET!,
      redirect_uri: 'https://yourapp.com/callback',
    },
  });

  // Persist the sk AND the signing_secret securely — both are returned only once
  await db.merchants.saveKeys(merchantId, {
    sk: keys.sk,
    pk: keys.pk,
    signing_secret: keys.signing_secret,
    pair_id: keys.pair_id,
    store_id: keys.store_id,
    environment: keys.environment,
    scopes: keys.scopes,
  });

  // If your app registered a webhook URL, a subscription was created automatically for this store.
  // Save its signing secret — you'll use it to verify inbound event POSTs (returned only once).
  if (keys.webhook_endpoint) {
    await db.merchants.saveWebhookSecret(merchantId, keys.webhook_endpoint.signing_secret);
  }

  res.redirect('/dashboard?connected=true');
}

3. Act on the merchant’s behalf

Spin up a client with the merchant’s sk and call the API as that store:

const merchant = new Tybrite({ apiKey: storedSecretKey });

const { orders } = await merchant.orders.listOrders({ limit: 20 });

4. Sign write requests

Reads need only the sk. Creating or updating an order, and initializing a payment, additionally require a signature computed with the signing_secret you stored at step 2:

Header	Value
`X-Timestamp`	Current Unix time, in seconds or milliseconds
`X-Signature`	Base64 HMAC-SHA256 of `${timestamp}.${requestBody}`

The signed string is the timestamp, a literal ., and the exact request body you send — sign the serialized bytes, not a re-serialized copy, or the signature won’t match. Signatures are accepted within five minutes of their timestamp.

import { createHmac } from 'node:crypto';

const body = JSON.stringify(orderPayload);
const timestamp = Math.floor(Date.now() / 1000).toString();
const signature = createHmac('sha256', storedSigningSecret)
  .update(`${timestamp}.${body}`)
  .digest('base64');

await fetch('https://api.tybritelabs.com/v1/orders', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${storedSecretKey}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': crypto.randomUUID(),
    'X-Timestamp': timestamp,
    'X-Signature': signature,
  },
  body,
});

An unsigned or mis-signed write returns 401 invalid_signature.

Store the sk and the signing_secret securely server-side immediately — both are returned only once and cannot be retrieved later. Treat them like passwords: keep them in a secrets manager, never in client-side code, logs, or version control.

Automatic webhooks

If your application processes events — reacting when a promotion goes live, a review is approved, or a store’s data changes — you can have a webhook subscription created for you the moment a merchant connects, with no separate setup step for them. Register a webhook URL on your application (in the developer portal, when you register or edit the app). From then on, every time a merchant connects, Galactic Core automatically creates a signed webhook subscription for their store pointing at that URL. The token-exchange response includes the subscription:

const keys = await client.gcConnect.connectToken({ requestBody: { code, client_id, client_secret, redirect_uri } });

if (keys.webhook_endpoint) {
  // {
  //   id: '…',
  //   url: 'https://yourapp.com/webhooks/galactic-core',
  //   events: ['promotion.activated', 'review.approved', 'feature.status_changed', …],
  //   signing_secret: '…',   // verify inbound POSTs with this — returned only once
  // }
}

webhook_endpoint.signing_secret is a different secret from signing_secret. signing_secret signs your outbound write requests (creating orders, initializing payments); webhook_endpoint.signing_secret verifies Galactic Core’s inbound event POSTs to your receiver. Store both, keep them apart.

Connecting the same merchant again updates that one subscription rather than creating duplicates, and it never touches an endpoint the merchant created by hand. If you did not register a webhook URL, webhook_endpoint is absent and the merchant (or your app) can still create one via the Webhooks API. The full event catalogue — including the store-lifecycle and feature-availability events that make this useful — is in the Webhooks reference; the pattern for keeping a storefront in step with a store is in Automated workflows.

Scopes

Scopes are passed space-separated in the scope parameter, and the merchant sees exactly the set you asked for on the consent screen. They are enforced on every request: a key calling an endpoint it was not granted is rejected with 403 insufficient_scope. A scope requested but never used therefore costs nothing at runtime and everything on the consent screen, which is the reason to request the narrowest set the integration needs.

Scope	Access
`read`	Coarse read (products, inventory, pricing, categories)
`write`	Coarse write (create / update products and inventory)
`products:read`	Read the product catalog and inventory
`categories:read`	Read categories and subcategories
`pricing:read`	Read dynamic pricing and price rules
`orders:read`	Read order history and status
`orders:write`	Create and update orders
`customers:read`	Read customer profiles
`customers:write`	Create and update customer records
`payments:read`	Read payment status and history
`cart:write`	Cart operations (browser-safe)
`cms:read`	Read blog posts and lookbooks
`shipping:read`	Read delivery zones and rates
`reviews:read`	Read product reviews and ratings
`reviews:write`	Submit and remove reviews
`gift_cards:read`	Check gift-card balances
`messaging:read`	Read customer conversation threads
`messaging:write`	Send messages in conversation threads
`returns:read`	Read returns and their status
`returns:write`	Lodge and update returns
`promotions:read`	Read promotions and discounts
`recommendations:read`	Read AI product recommendations
`search:read`	Run catalog and semantic search
`store:read`	Read store metadata and settings

Sandbox vs production

The environment parameter on the authorization URL decides whether the resulting key pair touches the merchant’s live data or isolated test data:

sandbox (default) — connect to test data while you build. Nothing you do affects the merchant’s real store.
production — connect to live store data. Use this once your integration is ready.

The merchant sees which environment you’re requesting on the consent screen, so be explicit. The returned environment field on the key pair confirms what was granted.

Lifecycle & revocation

Connected keys are permanent — they don’t expire on a timer. A connection ends in one of two ways:

The merchant disconnects you from their store’s Integrations → API Keys → Connected Apps panel. Galactic Core deactivates the key pair automatically — you don’t need to do anything.
You revoke the connection with connectRevoke (passing the pair_id you saved at exchange time) — for example, when a merchant cancels their subscription on your platform.

await client.gcConnect.connectRevoke({
  requestBody: {
    pair_id: storedPairId,
    client_id: process.env.GC_CLIENT_ID!,
    client_secret: process.env.GC_CLIENT_SECRET!,
    revoke_reason: 'subscription_cancelled', // optional
  },
});

To see every store currently connected to your application — the data behind a merchant’s Connected Apps panel — call listConnectSessions with a secret key:

const { sessions } = await client.gcConnect.listConnectSessions();

Security checklist

Generate a fresh random state per authorization and verify it on the callback (CSRF protection)
Run the code-for-keys exchange server-side only — never expose client_secret to a browser
Store each merchant’s sk in a secrets manager, scoped to that merchant
Store each merchant’s signing_secret alongside it — it is returned only once, and without it you cannot create orders or initialize payments for that merchant
Request the minimum scopes your integration needs
Save the pair_id so you can revoke the connection later
Use HTTPS for your redirect_uri, and register it exactly in the Developer Portal

SDK reference

See the GcConnectService SDK reference for full method signatures, or the API Reference for the raw endpoints.

Introduction

How GC Works

Build with AI

Extend the platform

Commerce capabilities

Distribute

Native Integrations

Resources

When to use it

The flow

Quick start

2. Handle the callback and exchange the code

3. Act on the merchant’s behalf

4. Sign write requests

Automatic webhooks

Scopes

Sandbox vs production

Lifecycle & revocation

Security checklist

SDK reference

​When to use it

​The flow

​Quick start

​1. Send the merchant to the consent screen

​2. Handle the callback and exchange the code

​3. Act on the merchant’s behalf

​4. Sign write requests

​Automatic webhooks

​Scopes

​Sandbox vs production

​Lifecycle & revocation

​Security checklist

​SDK reference

When to use it

The flow

Quick start

1. Send the merchant to the consent screen

2. Handle the callback and exchange the code

3. Act on the merchant’s behalf

4. Sign write requests

Automatic webhooks

Scopes

Sandbox vs production

Lifecycle & revocation

Security checklist

SDK reference