Organizations & Merchants

Tokeflow is multi-tenant by design. Every account is modeled as an Organization that owns one or more Merchants. This two-level hierarchy is the foundation for how you authenticate, scope data, and govern access across your platform.

You integrate at one of two levels:

• Organization level — one set of credentials that operates across every merchant in the org. Ideal for platforms and back-office systems.
• Merchant level — credentials scoped to a single merchant, where the merchant is inferred automatically. Ideal for a single store.

This page explains the hierarchy and helps you pick the right integration level. For header formats and key handling, see Authentication.

The hierarchy

An Organization is the top-level tenant. It owns Merchants. Each Merchant is fully isolated: it has its own API credentials, product catalog, customers, transactions, and webhook endpoints. Data never leaks across merchant boundaries.

Organization-level integration

An Organization key spans every merchant in the org. Use it from a central platform or back-office system that needs to operate on behalf of many merchants with one credential.

Because an org key is not bound to a single merchant, you must tell Tokeflow which merchant a merchant-scoped operation targets:

• List and read endpoints: pass the merchant as the merchant_id query parameter.
• Create endpoints: pass merchant_id in the request body.

Omitting merchant_id on a merchant-scoped operation returns 400 validation_error.

# Organization key — list a specific merchant's transactions
curl https://api.tokeflow.com/api/v1/transactions?merchant_id=mrc_123&page=1&limit=20 \
  -H "Authorization: Bearer sk_live_org_xxxxxxxxxxxxxxxxxxxx"

// Organization key — create a customer for a specific merchant
const res = await fetch("https://api.tokeflow.com/api/v1/customers", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.TOKEFLOW_ORG_SECRET_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID(),
  },
  body: JSON.stringify({
    merchant_id: "mrc_123", // required for org keys on merchant-scoped resources
    email: "ada@example.com",
    name: "Ada Lovelace",
  }),
});

If merchant_id is missing, the API responds:

{
  "error": {
    "type": "validation_error",
    "code": "MERCHANT_ID_REQUIRED",
    "message": "merchant_id is required when using organization API keys",
    "details": {},
    "request_id": "req_8f3c2a1b9d",
    "timestamp": "2026-01-15T12:30:00.000Z"
  }
}

Merchant-level integration

A Merchant key is permanently scoped to one merchant. The merchant is inferred from the key — you never pass merchant_id. Use it for a single store or any integration that only ever touches one merchant.

# Merchant key — list this merchant's transactions (no merchant_id needed)
curl https://api.tokeflow.com/api/v1/transactions?page=1&limit=20 \
  -H "Authorization: Bearer sk_live_mer_xxxxxxxxxxxxxxxxxxxx"

// Merchant key — create a customer (merchant is inferred)
const res = await fetch("https://api.tokeflow.com/api/v1/customers", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.TOKEFLOW_MERCHANT_SECRET_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID(),
  },
  body: JSON.stringify({
    email: "ada@example.com",
    name: "Ada Lovelace",
  }),
});

A successful response is wrapped in the standard success envelope:

{
  "success": true,
  "data": {
    "id": "cust_4f9a1c2e7b",
    "merchant_id": "mrc_123",
    "email": "ada@example.com",
    "name": "Ada Lovelace",
    "created_at": "2026-01-15T12:30:00.000Z",
    "updated_at": "2026-01-15T12:30:00.000Z"
  },
  "request_id": "req_8f3c2a1b9d",
  "timestamp": "2026-01-15T12:30:00.000Z"
}

Organization key vs Merchant key

Both key levels exist as secret keys (sk_…, server-side only) and public keys (pk_…, client-safe). The level controls which entity the key acts on; the type controls where it can be used. See Authentication for key anatomy and handling.

When to use which

Choose the integration level that matches how your system maps to merchants.

Use an Organization key when:

• You run a platform or marketplace that manages many merchants.
• A back-office, billing, or analytics service needs org-wide visibility.
• You provision or reconcile data across stores from one place.

Use a Merchant key when:

• You are integrating a single store or brand.
• You want the simplest possible requests — no merchant_id to manage.
• You want to limit a credential's blast radius to one merchant.

Next steps

• Authentication — key anatomy, headers, secret vs public keys, and security rules.