Multi-Tenancy

Wetel is multi-tenant by default. This page covers the model itself and the practical pattern for building a platform on top of Wetel that serves multiple end-customers of your own (a system integrator, reseller, or any product that embeds Wetel for more than one client).

The one-tenant-per-customer model

• Every account belongs to exactly one tenant. Data — agents, workflows, tools, knowledge bases, sessions, users, API keys — is fully isolated per tenant at the data layer.
• The GraphQL surface is identical across tenants. Every tenant calls the same mutations and subscriptions (sdkStart, sdkSendMessage, createAgent, createMcpConnector, and so on) — only the data behind them differs.
• There is no cross-tenant visibility anywhere in the API. A request authenticated for one tenant cannot see or affect another tenant’s data, regardless of IDs guessed or enumerated.

API keys are scoped to a tenant

When you call generateApiKey, the returned key is bound to the tenant of the authenticated user who requested it:

mutation GenerateKey {
  generateApiKey {
    key
    warning
  }
}

• That key can only start sessions against agents and workflows belonging to its own tenant.
• A key from one tenant cannot see or act on another tenant’s data, even if it were somehow obtained by a third party.
• key is returned exactly once — store it in your backend’s environment, never in client-side code. See Authentication for the full two-tier key/token model.

The gateway pattern for system integrators

If you’re building a platform that serves multiple end-customers, each of whom has their own Wetel tenant, don’t expose any customer’s Wetel API key to that customer’s own frontend. Instead, your backend acts as a gateway that holds every customer’s key server-side and proxies calls on their behalf.

sequenceDiagram
  participant CF as Customer's Frontend
  participant SI as Your Backend (Gateway)
  participant W as Wetel

  CF->>SI: POST /api/chat/start?customerId=123
  SI->>SI: look up Customer 123's stored X-Api-Key
  SI->>W: sdkStart(input: { agentId }) [X-Api-Key, x-huat-platform]
  W-->>SI: { sessionId, avatarToken }
  SI-->>CF: sessionId, avatarToken
  Note over CF,W: From here, the flow is a standard single-tenant integration

How it works:

1. Each of your customers has their own Wetel tenant and generates their own X-Api-Key (via their own dashboard login, or one you provision on their behalf).
2. Your backend stores each customer’s key server-side — in your own database or secrets manager — keyed by your own customerId.
3. When a customer’s end-user opens a chat, your frontend calls your own backend (not Wetel directly), passing your own customerId.
4. Your backend looks up that customer’s stored key and calls sdkStart with it, addressed to that customer’s agent.
5. Wetel returns a short-lived avatarToken and sessionId, scoped to that customer’s tenant.
6. Your backend hands the avatarToken/sessionId to the customer’s frontend. From this point on, the integration is identical to a standard single-tenant flow — see Core API Flow.

What this buys you:

• A single Wetel-facing backend serving all of your customers, with no special multi-tenant logic needed in any customer-facing frontend code — Wetel enforces tenant isolation server-side.
• No customer’s long-lived X-Api-Key is ever exposed to a browser, regardless of how many end-customers you serve. Only the short-lived, session-scoped avatarToken reaches the frontend, exactly as in a single-tenant integration.

What not to do:

• Never pass a customer’s X-Api-Key to that customer’s frontend, “just for their own tenant.” The key grants full access to everything in that tenant — agents, workflows, tools, and sessions — for as long as it’s valid (months to years). Treat it exactly like a database credential: it lives in your backend only.
• Never share one X-Api-Key across multiple end-customers as a shortcut. Each customer should have their own tenant and their own key, so a compromise or a bug on one customer’s integration can’t reach another’s data.

Next steps

• Authentication — the full two-tier API-key / avatar-token model this pattern builds on.
• Core API Flow — the sdkStart → sdkSendMessage → sdkEndSession flow your gateway proxies.
• Agents — configuring the agent each of your customers will attach their key to.