Self-Hosted Multi-Tenant RAG Application

Build a production multi-tenant RAG app with tenant-scoped TypeGraph clients, document ingest, events, and search.

Cache Clients by Tenant

Create one TypeGraph client per customer tenant. In Cloud, API-key auth resolves your TypeGraph organization, while tenantId selects the customer graph. In self-hosted mode, the same pattern works with your own adapter config.

typegraph-factory.ts

import { cache } from 'react'
import { TenantId, typegraphInit } from '@typegraph-ai/sdk'

export const getTypeGraph = cache(async (tenantId: string) => {
  return typegraphInit({
    apiKey: process.env.TYPEGRAPH_API_KEY!,
    tenantId: TenantId(tenantId),
  })
})

Require X-Tenant-Id

API routes should require X-Tenant-Id. Do not expose tenant choice as organization ID or as a top-level body field. If internal SDK payloads carry identity.tenantId, validate that it matches the header.

tenant-header.ts

function validateTenantHeader(req: Request, body: unknown) {
  const tenantId = req.headers.get('x-tenant-id')
  if (!tenantId) throw new Error('Missing X-Tenant-Id')

  const bodyTenantId =
    typeof body === 'object' && body && 'identity' in body
      ? (body as { identity?: { tenantId?: string } }).identity?.tenantId
      : undefined

  if (bodyTenantId && bodyTenantId !== tenantId) {
    throw new Error('Body tenant does not match X-Tenant-Id')
  }

  return tenantId
}

Ingest Documents

Document ingest should call typegraph.document.ingest() and pass all per-call identity and write access under context.

documents-route.ts

export async function POST(req: Request) {
  const tenantId = req.headers.get('x-tenant-id')
  if (!tenantId) {
    return Response.json({ error: 'Missing X-Tenant-Id' }, { status: 400 })
  }

  const typegraph = await getTypeGraph(tenantId)
  const body = await req.json()

  const result = await typegraph.document.ingest(body.documents, {
    bucketId: body.bucketId,
    graphExtraction: body.graphExtraction ?? false,
    context: body.context,
    idempotencyKey: body.idempotencyKey,
  })

  return Response.json(result)
}

Search Tenant Data

Search always runs inside the tenant-bound client. context narrows readable records; resources and weights control retrieval and scoring.

search.ts

export async function searchTenant(
  tenantId: string,
  query: string,
  context: {
    groupId?: string
    userId?: string
    agentId?: string
    threadId?: string
  },
) {
  const typegraph = await getTypeGraph(tenantId)

  return typegraph.search(query, {
    resources: ['documents', 'events', 'entities', 'facts'],
    weights: { semantic: 1, bm25: 0.7, graph: 0.5, recency: 0.3 },
    context,
    limit: 10,
    promptBuilder: true,
  })
}

Back to All Guides

import { cache } from 'react' import { TenantId, typegraphInit } from '@typegraph-ai/sdk' export const getTypeGraph = cache(async (tenantId: string) => { return typegraphInit({ apiKey: process.env.TYPEGRAPH_API_KEY!, tenantId: TenantId(tenantId), }) })

function validateTenantHeader(req: Request, body: unknown) { const tenantId = req.headers.get('x-tenant-id') if (!tenantId) throw new Error('Missing X-Tenant-Id') const bodyTenantId = typeof body === 'object' && body && 'identity' in body ? (body as { identity?: { tenantId?: string } }).identity?.tenantId : undefined if (bodyTenantId && bodyTenantId !== tenantId) { throw new Error('Body tenant does not match X-Tenant-Id') } return tenantId }

export async function POST(req: Request) { const tenantId = req.headers.get('x-tenant-id') if (!tenantId) { return Response.json({ error: 'Missing X-Tenant-Id' }, { status: 400 }) } const typegraph = await getTypeGraph(tenantId) const body = await req.json() const result = await typegraph.document.ingest(body.documents, { bucketId: body.bucketId, graphExtraction: body.graphExtraction ?? false, context: body.context, idempotencyKey: body.idempotencyKey, }) return Response.json(result) }

export async function searchTenant( tenantId: string, query: string, context: { groupId?: string userId?: string agentId?: string threadId?: string }, ) { const typegraph = await getTypeGraph(tenantId) return typegraph.search(query, { resources: ['documents', 'events', 'entities', 'facts'], weights: { semantic: 1, bm25: 0.7, graph: 0.5, recency: 0.3 }, context, limit: 10, promptBuilder: true, }) }