> ## Documentation Index
> Fetch the complete documentation index at: /docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuração multi-tenant

> Isole e delimite o uso do AI Gateway por tenant com Identities ou metadados de requisição, e aplique orçamentos, roteamento e observabilidade por tenant.

Consulte [URLs e autenticação HTTP](/docs/pt-BR/reference/base-urls.md) 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](#isolating-data-and-knowledge-bases-per-tenant).

> [!NOTE]
>
> **Agentes gerenciados**: um único agente atende todos os tenants. O agente fica em um único projeto, e cada execução anexa a [Identity](#approach-1-identity-per-tenant) 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](#isolating-data-and-knowledge-bases-per-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](/docs/pt-BR/ai-studio/observability/reporting-api.md); 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**](/docs/pt-BR/ai-studio/observability/identities.md) 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:

```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
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:

```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
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"
    }
  }'
```

```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
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);
```

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
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](/docs/pt-BR/ai-studio/observability/identities.md#attaching-an-identity-to-a-request) 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**](/docs/pt-BR/ai-gateway/request-metadata.md). 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:

```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
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"
    }
  }'
```

```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
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);
```

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
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:

```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
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](/docs/pt-BR/ai-studio/observability/reporting-api.md) 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.

> [!NOTE]
>
> 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](/docs/pt-BR/ai-gateway/request-metadata.md#best-practices).

## 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.

**1. Crie a identity do tenant**

```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
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"
}'
```

**2. 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](/docs/pt-BR/ai-gateway/budgets.md) para limites por período e alertas.

> [!WARNING]
>
> 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.

**3. 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:

```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
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" }
    }
  }'
```

```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
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" },
  },
});
```

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
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](/docs/pt-BR/ai-gateway/configuration/routing-rules.md) 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.

**4. Reporte o uso e o custo da Acme**

Consulte a [Reporting API](/docs/pt-BR/ai-studio/observability/reporting-api.md), filtrando pela identity do tenant:

```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
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.

> [!NOTE]
>
> 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

> [card] [Identities](/docs/pt-BR/ai-studio/observability/identities.md)
>
> Crie identities e anexe-as às requisições para atribuição e orçamentos por tenant.

> [card] [Metadados de requisição](/docs/pt-BR/ai-gateway/request-metadata.md)
>
> Anexe nome, identity, thread e metadados personalizados às requisições do AI Gateway.

> [card] [Orçamentos](/docs/pt-BR/ai-gateway/budgets.md)
>
> Limite o gasto por workspace, projeto, identity, chave de API, provedor ou modelo.

> [card] [Reporting API](/docs/pt-BR/ai-studio/observability/reporting-api.md)
>
> Consulte programaticamente o uso, o custo e o desempenho por tenant.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.