Configuração multi-tenant

Consulte URLs e autenticação HTTP e a referência da API para os formatos completos de solicitação e resposta. Quando uma única implantação do AI Gateway atende vários clientes, equipes ou produtos, as requisições de cada tenant precisam ser rastreadas e isoladas para que o uso, o custo e os traces possam ser reportados por tenant. O Toqan Router oferece dois mecanismos no nível da requisição para isso:

Identities, que representam um tenant ou seus usuários finais em cada requisição.
Metadados de requisição, que marcam uma chamada com um ID de tenant ou outros dados de chave-valor.

Este guia aborda as duas abordagens, quando usar cada uma e um exemplo prático que roteia, define orçamento e observa um único tenant de ponta a ponta. Para isolar os dados que essas requisições recuperam (por exemplo, bases de conhecimento por tenant), consulte Isolar dados e bases de conhecimento por tenant.

Agentes gerenciados: um único agente atende todos os tenants. O agente fica em um único projeto, e cada execução anexa a Identity daquele tenant, que carrega os relatórios, os orçamentos e os filtros de traces. Um projeto por tenant vem depois, quando as bases de conhecimento ou os datasets de um tenant precisarem de um limite próprio; consulte Isolar dados e bases de conhecimento por tenant.

Qual abordagem usar

Escolha a abordagem de acordo com o quanto cada tenant é fixo e com o que precisa ser aplicado ou reportado. Use uma Identity para tenants ou usuários finais conhecidos e estáveis, quando o custo e o uso precisarem ser medidos, limitados e reportados por identity. Use metadados quando as requisições precisarem apenas de uma marcação para filtrar depois e o tenant não for algo sobre o qual aplicar um orçamento.

	Identity por tenant	Metadados de requisição
Representa	Um tenant ou usuário final conhecido e endereçável	Contexto arbitrário de chave-valor em uma requisição
Transporte	Objeto `identity` ou header `X-TOQAN-IDENTITY-ID`	Objeto `metadata` ou headers `X-TOQAN-METADATA-*`
Relatórios de custo e uso	Agrupados e filtrados por identity	Não é uma dimensão de Reporting; apenas filtro de traces
Orçamentos	Limites de orçamento por identity	Não é um escopo de orçamento
Traces e analytics	Filtrados por Identity	Filtrados por `metadata.<key>`
Ideal para	Faturamento por tenant, orçamentos por tenant, atribuição a usuários finais	Tenants que não se encaixam bem em uma identity fixa, marcações ad hoc

Abordagem 1: Identity por tenant

Uma Identity representa um User, Team, Project ou Client. Crie uma identity por tenant e anexe-a a todas as requisições feitas por esse tenant. O uso, o custo e os traces passam então a ser atribuídos à identity, permitindo relatórios por tenant, orçamentos por identity e filtragem de traces. Crie uma identity para cada tenant uma única vez:

curl --location 'https://router.toqan.ai/eu/v2/identities' \
--header "Authorization: Bearer $TOQAN_API_KEY" \
--header 'Content-Type: application/json' \
--data-raw '{
    "external_id": "tenant-acme",
    "display_name": "Acme Corp",
    "metadata": {
      "plan": "enterprise"
    }
}'

Em seguida, passe a identity em cada requisição, no corpo ou como header:

curl -X POST https://router.toqan.ai/eu/v3/router/responses \
  -H "Authorization: Bearer $TOQAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-5.4-mini",
    "input": "Help me resolve a billing issue",
    "name": "SupportAssistant-Production",
    "identity": {
      "id": "tenant-acme"
    }
  }'

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.TOQAN_API_KEY,
  baseURL: "https://router.toqan.ai/eu/v3/router",
});

const response = await client.responses.create({
  model: "openai/gpt-5.4-mini",
  input: "Help me resolve a billing issue",
  name: "SupportAssistant-Production",
  identity: { id: "tenant-acme" },
});

console.log(response.output_text);

from openai import OpenAI
import os

client = OpenAI(
    api_key=os.environ.get("TOQAN_API_KEY"),
    base_url="https://router.toqan.ai/eu/v3/router",
)

response = client.responses.create(
    model="openai/gpt-5.4-mini",
    input="Help me resolve a billing issue",
    extra_body={
        "name": "SupportAssistant-Production",
        "identity": {"id": "tenant-acme"},
    },
)

print(response.output_text)

Para rastrear tanto um tenant quanto a pessoa que age em nome dele, dê a cada usuário final um ID de identity como tenant-{orgId}-{userId}, ou crie uma identity por tenant e compartilhe-a entre os usuários desse tenant. Consulte Anexar uma identity a uma requisição para conhecer as fontes corpo, header e proprietário da chave de API, na ordem em que o gateway as verifica.

Abordagem 2: Metadados de requisição

Para tenants que não correspondem a um conjunto fixo de identities, marque as requisições com metadados de requisição. Os metadados adicionam contexto de chave-valor, como tenant_id, region ou tier, que aparece nos traces como atributos de span metadata.<key> e pode ser usado como filtro de traces. Passe um objeto metadata na requisição:

curl -X POST https://router.toqan.ai/eu/v3/router/responses \
  -H "Authorization: Bearer $TOQAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-5.4-mini",
    "input": "Summarize my contracts",
    "metadata": {
      "tenant_id": "acme",
      "region": "eu-west-1"
    }
  }'

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.TOQAN_API_KEY,
  baseURL: "https://router.toqan.ai/eu/v3/router",
});

const response = await client.responses.create({
  model: "openai/gpt-5.4-mini",
  input: "Summarize my contracts",
  metadata: { tenant_id: "acme", region: "eu-west-1" },
});

console.log(response.output_text);

from openai import OpenAI
import os

client = OpenAI(
    api_key=os.environ.get("TOQAN_API_KEY"),
    base_url="https://router.toqan.ai/eu/v3/router",
)

response = client.responses.create(
    model="openai/gpt-5.4-mini",
    input="Summarize my contracts",
    extra_body={"metadata": {"tenant_id": "acme", "region": "eu-west-1"}},
)

print(response.output_text)

Quando o corpo da requisição não puder ser modificado, defina os metadados com headers. Cada header X-TOQAN-METADATA-<key> define uma chave de metadados, em minúsculas, a partir do sufixo do header:

cURL

curl -X POST https://router.toqan.ai/eu/v3/router/responses \
  -H "Authorization: Bearer $TOQAN_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-TOQAN-METADATA-TENANT_ID: acme" \
  -H "X-TOQAN-METADATA-REGION: eu-west-1" \
  -d '{
    "model": "openai/gpt-5.4-mini",
    "input": "Summarize my contracts"
  }'

Os metadados alimentam regras de roteamento, regras de guardrail e a correspondência de orçamentos, e aparecem como filtro de traces, então as requisições podem ser roteadas, protegidas e inspecionadas por tenant sem uma identity. Os metadados não são uma dimensão de Reporting nem um escopo de orçamento. Para agregar o custo por tenant ou limitar o gasto de um tenant, use o escopo de identity ou de projeto.

Mantenha os metadados em um conjunto pequeno e fixo de chaves de baixa cardinalidade, como tenant_id, region e tier. Valores de alta cardinalidade, como IDs por requisição, inviabilizam a filtragem e aumentam o armazenamento. Consulte Boas práticas de metadados de requisição.

Identity e metadados juntos

Use uma Identity para medir e definir o orçamento de um tenant; use metadados para contexto adicional, como região ou linha de produto. Os dois funcionam juntos: anexe a Identity do tenant para atribuição e orçamentos por tenant e, em seguida, adicione metadados para descrever a requisição.

Exemplo prático: um tenant, de ponta a ponta

Este exemplo configura a Acme Corp como um tenant com roteamento por tenant, um orçamento mensal e observabilidade por tenant, usando uma identity e uma regra de roteamento baseada em identity e metadados.

Crie a identity do tenant

curl --location 'https://router.toqan.ai/eu/v2/identities' \
--header "Authorization: Bearer $TOQAN_API_KEY" \
--header 'Content-Type: application/json' \
--data-raw '{
    "external_id": "tenant-acme",
    "display_name": "Acme Corp"
}'

Limite o gasto da Acme

Acesse Settings > Organization > Budgets e clique em Create. Defina Scope > Applies to como Identity, selecione a identity tenant-acme e defina um limite mensal de Cost. Quando o limite é atingido, as requisições que correspondem à identity da Acme são rejeitadas até a renovação mensal, enquanto os outros tenants continuam funcionando. Consulte Orçamentos para limites por período e alertas.

Qualquer pessoa com uma chave pode definir uma Identity em uma requisição; o gateway não verifica se a chave é dona dessa identity. Portanto, os orçamentos e os relatórios de custo baseados em identity são tão confiáveis quanto as chaves que podem acessar o gateway. Forneça chaves apenas a backends confiáveis. Para limitar o gasto de tenants não confiáveis, use uma chave por tenant ou um projeto por tenant em vez da correspondência por identity.

Roteie e observe o tráfego da Acme

Em cada requisição, anexe a identity e uma chave de metadados para que o roteamento e os filtros de traces possam direcionar a Acme:

curl -X POST https://router.toqan.ai/eu/v3/router/responses \
  -H "Authorization: Bearer $TOQAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "agent/support-bot",
    "input": "Reset my password",
    "identity": {
      "id": "tenant-acme"
    },
    "metadata": {
      "tenant_id": "acme"
    },
    "memory": {
      "entity_id": "tenant-acme"
    },
    "tools": [
      {
        "type": "mcp",
        "server_url": "https://mcp.acme.example/mcp",
        "headers": { "Authorization": "Bearer {{acme_token}}" }
      }
    ],
    "variables": {
      "acme_token": { "secret": true, "value": "acme-mcp-token" }
    }
  }'

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.TOQAN_API_KEY,
  baseURL: "https://router.toqan.ai/eu/v3/router",
});

const response = await client.responses.create({
  model: "agent/support-bot",
  input: "Reset my password",
  identity: { id: "tenant-acme" },
  metadata: { tenant_id: "acme" },
  memory: { entity_id: "tenant-acme" },
  tools: [
    {
      type: "mcp",
      server_url: "https://mcp.acme.example/mcp",
      headers: { Authorization: "Bearer {{acme_token}}" },
    },
  ],
  variables: {
    acme_token: { secret: true, value: "acme-mcp-token" },
  },
});

from openai import OpenAI
import os

client = OpenAI(
    api_key=os.environ.get("TOQAN_API_KEY"),
    base_url="https://router.toqan.ai/eu/v3/router",
)

response = client.responses.create(
    model="agent/support-bot",
    input="Reset my password",
    extra_body={
        "identity": {"id": "tenant-acme"},
        "metadata": {"tenant_id": "acme"},
        "memory": {"entity_id": "tenant-acme"},
        "tools": [
            {
                "type": "mcp",
                "server_url": "https://mcp.acme.example/mcp",
                "headers": {"Authorization": "Bearer {{acme_token}}"},
            }
        ],
        "variables": {"acme_token": {"secret": True, "value": "acme-mcp-token"}},
    },
)

O armazenamento de memória é delimitado a tenant-acme, então cada tenant mantém sua própria memória de conversa. O token do MCP chega como uma variável secret e fica fora dos traces e logs; consulte Credenciais por requisição para as regras de placeholders e segredos.Crie uma Routing Rule cuja condição corresponda à Identity tenant-acme para enviar o tráfego da Acme a um modelo ou variante dedicado. Combine condições de identity e metadados (por exemplo, região) com o construtor de regras.

Reporte o uso e o custo da Acme

Consulte a Reporting API, filtrando pela identity do tenant:

FROM=$(date -u -v-1d +%Y-%m-%dT%H:%M:%SZ 2>/dev/null || date -u -d "1 day ago" +%Y-%m-%dT%H:%M:%SZ)
TO=$(date -u +%Y-%m-%dT%H:%M:%SZ)
curl -X POST "https://router.toqan.ai/eu/v2/reporting" \
  -H "Authorization: Bearer $TOQAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"metric\": \"genai.usage\",\"from\": \"$FROM\",\"to\": \"$TO\",\"grain\": \"day\",\"group_by\": [\"identity\"],\"filters\": [{\"field\": \"identity\",\"op\": \"eq\",\"values\": [\"tenant-acme\"]}]}"

Na visualização Traces, filtre por Identity tenant-acme ou por Metadata tenant_id: acme para inspecionar a latência, o uso de tokens e os erros da Acme.

Execuções agendadas de agentes não carregam identity, então seu custo e uso não são atribuídos a um tenant. Quando as execuções agendadas precisarem de Reporting por tenant, execute-as a partir de um agendador do lado do cliente que chame a Responses API com identity anexada, ou leia o custo delas na visualização Traces filtrada por metadados.

Isolar dados e bases de conhecimento por tenant

A atribuição no nível da requisição mede o uso, mas não separa os dados que um tenant pode recuperar. Para isolar o conteúdo, coloque cada tenant em seu próprio Project.

Os projetos são o limite de isolamento. Um Project contém Deployments, Prompts, Agents, Knowledge Bases e Datasets, com observabilidade e orçamentos delimitados ao projeto.
As bases de conhecimento acompanham o projeto. Uma base de conhecimento fica sob um project/path e é recuperada por meio de um Deployment nesse projeto. Com um projeto por tenant, a chave de um tenant não consegue acessar a base de conhecimento de outro tenant.
Chaves de projeto único ficam dentro do tenant. Apenas chaves criadas com escopo de projeto único ficam confinadas ao projeto daquele tenant. Chaves de todo o workspace e chaves legadas podem acessar todos os projetos, portanto emita chaves de projeto único para os tenants e nunca entregue uma chave de todo o workspace.
Ou compartilhe uma base de conhecimento entre tenants confiáveis. Se os tenants confiarem uns nos outros, marque os chunks com um campo de metadados client_id e adicione uma condição filter_by para restringir a recuperação àquele tenant. Trata-se de um filtro no momento da consulta, e não de um controle de acesso imposto: qualquer chamador pode omiti-lo e ler os chunks de todos os tenants. Use-o apenas entre tenants confiáveis; caso contrário, separe os tenants em projetos por tenant. Consulte Metadados de chunks em bases de conhecimento.

Para uma configuração completa: um projeto por tenant para isolamento de dados e orçamentos por tenant, uma Identity (ou a chave delimitada ao projeto) para que os relatórios de uso e os traces sejam atribuídos ao tenant, e metadados para contexto adicional, como região ou linha de produto.

Veja também

Identities

Crie identities e anexe-as às requisições para atribuição e orçamentos por tenant.

Metadados de requisição

Anexe nome, identity, thread e metadados personalizados às requisições do AI Gateway.

Orçamentos

Limite o gasto por workspace, projeto, identity, chave de API, provedor ou modelo.

Reporting API

Consulte programaticamente o uso, o custo e o desempenho por tenant.

Toqan Router

Visão geral

APIs

MCP Portal

Roteamento

Segurança e privacidade

Recursos dos modelos

Ferramentas de servidor

Cenários comuns

Configuração de provedores

Qual abordagem usar

Abordagem 1: Identity por tenant

Abordagem 2: Metadados de requisição

Identity e metadados juntos

Exemplo prático: um tenant, de ponta a ponta

Isolar dados e bases de conhecimento por tenant

Veja também

Identities

Metadados de requisição

Orçamentos

Reporting API

​Qual abordagem usar

​Abordagem 1: Identity por tenant

​Abordagem 2: Metadados de requisição

​Identity e metadados juntos

​Exemplo prático: um tenant, de ponta a ponta

​Isolar dados e bases de conhecimento por tenant

​Veja também

Identities

Metadados de requisição

Orçamentos

Reporting API

Qual abordagem usar

Abordagem 1: Identity por tenant

Abordagem 2: Metadados de requisição

Identity e metadados juntos

Exemplo prático: um tenant, de ponta a ponta

Isolar dados e bases de conhecimento por tenant

Veja também