Multi-Tenant Setup

This example walks through setting up an Inconvo agent for a multi-tenant SaaS application where each organisation should only see their own data.

Scenario

You have an ecommerce analytics database shared by multiple organisations. Each organisation has their own users, orders, and products. Every table has an organisation_id column.

Setup

1. Connect your database

   Follow the Connect a Database guide to add your database connection.

2. Define user context fields

   In the Inconvo dashboard, go to Configure and define a user context field:

   • Field name: organisationId
   • Type: integer

3. Set context filters on every queryable table

   For each table that should be scoped to a tenant, add a context filter:

   -- users table
   WHERE users.organisation_id = userContext.organisationId;
   
   -- orders table
   WHERE orders.organisation_id = userContext.organisationId;
   
   -- products table
   WHERE products.organisation_id = userContext.organisationId;

   Danger

   Every Queryable table must have a context filter. If you miss a table, queries against it will return data across all tenants.

4. Add table prompts for business context

   Add prompts to help the agent understand your data:

   users table: Users are also referred to as accounts. A user is considered a customer if the last_order_at is not null.

5. Create conversations with userContext

   When creating a conversation from your backend, pass the tenant’s organisationId:

   import Inconvo from "@inconvoai/node";
   
   const inconvo = new Inconvo({
     apiKey: process.env.INCONVO_API_KEY,
   });
   
   // Get the organisationId from your authenticated user's session
   const organisationId = req.user.organisationId;
   
   const conversation = await inconvo.agents.conversations.create(
     process.env.INCONVO_AGENT_ID,
     {
       userIdentifier: req.user.id,
       userContext: {
         organisationId,
       },
     },
   );

6. Verify data isolation

   Create conversations with different organisationId values and confirm each returns only that organisation’s data.

What happens at query time

When a user in organisation 1 asks “How many orders did we have last month?”, Inconvo will:

1. Identify the orders table as relevant
2. Apply the context filter: WHERE orders.organisation_id = 1
3. Add the time filter for “last month”
4. Return only organisation 1’s order count

The user never sees data from other organisations.