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

# Mascarar conteúdo sensível em traces

> Controle qual conteúdo de solicitações e respostas é gravado nos traces armazenados com o parâmetro security no AI Gateway, sem alterar a saída em tempo real.

**Casos de uso**

* Manter os prompts de sistema fora dos traces armazenados, continuando a rastrear a solicitação.
* Excluir dos logs o conteúdo enviado pelos usuários para atender a requisitos de tratamento de dados.
* Remover a saída do modelo dos traces sem alterar o que o chamador recebe.

O parâmetro `security` controla o que é gravado nos traces armazenados. Ele não altera a solicitação nem a resposta em tempo real: o chamador sempre recebe a saída completa e sem máscara. Apenas a cópia persistida no armazenamento de traces é afetada.

> [!WARNING]
>
> Mascarar `input`, `output`, `system` ou `all` com `security.mask` afeta apenas a cópia da solicitação gravada nos traces armazenados. **O payload completo e sem máscara continua sendo enviado ao provedor do modelo.** Para evitar que PII saia na solicitação ou na resposta em tempo real, ative o plugin [**PII Redaction**](/docs/pt-BR/ai-gateway/features/plugins/pii-redaction.md).

> [!NOTE]
>
> `security` é definido por solicitação. Não há padrão de workspace, projeto ou chave de API; assim, uma solicitação que não envia um bloco `security` é registrada por completo, a menos que se aplique uma máscara no nível do workspace. Para mascarar todas as solicitações sem repetir o campo, ative o [Trace Scrubbing](/docs/pt-BR/ai-gateway/features/plugins/trace-scrubbing.md) para o workspace, observadas as rotas listadas em [Cobertura](#coverage). Para anexar o campo automaticamente, defina-o como padrão no cliente do SDK.

## Comparação com o Trace Scrubbing

O **Trace Data Masking** (esta página) e o [Trace Scrubbing](/docs/pt-BR/ai-gateway/features/plugins/trace-scrubbing.md) decidem o que o **AI Gateway** grava em um trace armazenado. Eles mascaram os mesmos campos com o mesmo código; portanto, a diferença não está no que é mascarado, mas em onde a máscara é definida e em quem pode alterá-la.

**O que é igual**

* Ambos aceitam `input`, `output`, `system`, `metadata`, `variables` ou `all`.
* Ambos apagam ou removem esses campos apenas do trace armazenado. A solicitação em tempo real, a resposta, o payload que o provedor recebe e os dados verificados por [**Guardrails**](/docs/pt-BR/ai-gateway/configuration/guardrail-rules.md) e **Evaluators** permanecem intactos.
* Uma solicitação que envia os dois é mesclada: as máscaras se somam, e nenhum dos lados remove uma máscara definida pelo outro.

**O que difere**

| | `security.mask` em uma solicitação | Plugin `trace_scrubbing` |
| - | - | - |
| Onde é definido | No bloco `security` da solicitação | No array `plugins` da solicitação, em uma [regra de roteamento](/docs/pt-BR/ai-gateway/configuration/routing-rules.md#plugins), em um MCP gateway ou para todo o workspace em [**Settings** > **Plugins**](/docs/pt-BR/ai-gateway/features/plugins/trace-scrubbing.md#enable-for-a-workspace) |
| Aplica-se sem que o chamador o envie | Não. Uma solicitação que omite o campo é registrada por completo, a menos que o workspace, uma regra ou um gateway adicione máscaras | Sim, nas configurações de workspace, de regra de roteamento e de MCP gateway; uma entrada `plugins` no escopo da solicitação ainda depende do chamador |
| Uma solicitação pode afrouxá-lo | Não se aplica: o chamador o define e, portanto, pode alterá-lo ou removê-lo a cada solicitação | Não. Uma solicitação pode adicionar máscaras, mas não pode remover uma definida pelo workspace, por uma regra ou por um gateway |
| Endpoints alcançados | Todos os endpoints em que é aplicado, incluindo `deployments/invoke`. /classify o ignora, e `images/edits` e `moderations` o aceitam sem aplicá-lo | Os mesmos endpoints, além de `/classify` e invocações de deployments quando definido no workspace ou em uma regra de roteamento, e os traces de chamadas de ferramentas que um MCP gateway armazena; os traces de `images/edits`, `moderations` e das rotas WebSocket de `/responses` e `/responses/compact` permanecem sem máscara |
| Seleção vazia | Permitida, e não mascara nada | Uma entrada de solicitação sem valores em `mask` é aceita e não mascara nada; uma configuração de regra de roteamento ou de MCP gateway a rejeita. Um toggle de workspace sem valores selecionados mascara tudo |

**Qual usar**: `security.mask` é adequado para um chamador que protege o próprio tráfego, com o custo de enviar o campo em cada solicitação. `trace_scrubbing` é adequado para uma política que deve valer para todos, pois um administrador a define uma única vez para o workspace, uma regra ou um gateway, e nenhum chamador pode desativá-la.

## Início rápido

```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 AI trends for 2025",
    "security": { "mask": ["input"] }
  }'
```

```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 AI trends for 2025",
  // @ts-ignore - Toqan Router extension
  security: { mask: ["input"] },
});

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 AI trends for 2025",
    extra_body={"security": {"mask": ["input"]}},
)

print(response.output_text)
```

```typescript TypeScript (Chat Completions) theme={"theme":{"light":"github-light","dark":"github-dark"}}
const response = await client.chat.completions.create({
  model: "openai/gpt-5.4-mini",
  messages: [{ role: "user", content: "Summarize AI trends for 2025" }],
  // @ts-ignore - Toqan Router extension
  security: { mask: ["input"] },
});
```

## Configuração

| Parâmetro | Tipo | Obrigatório | Descrição |
| - | - | - | - |
| `mask` | string\[] | Não | Qual conteúdo mascarar nos traces armazenados: `input`, `output`, `system`, `metadata`, `variables` ou `all`. |

Um valor não reconhecido em `mask` é rejeitado com um erro 400.

## O que cada valor mascara

| Valor | Efeito nos traces armazenados |
| - | - |
| `input` | Apaga o conteúdo das mensagens de usuário e (em spans de ferramentas) os argumentos das chamadas de ferramentas. |
| `system` | Apaga o conteúdo das mensagens de sistema e de desenvolvedor e (em spans de ferramentas) as variáveis de ferramentas resolvidas. Também remove `description` e o schema de parâmetros (`parameters` ou `input_schema`) das definições de ferramentas, mantendo apenas o nome e o tipo. |
| `output` | Apaga o conteúdo das mensagens do assistente, incluindo o texto de raciocínio, e (em spans de ferramentas) o resultado das chamadas de ferramentas. Os resumos de raciocínio e o conteúdo de raciocínio criptografado permanecem no span. |
| `metadata` | Remove os metadados personalizados da solicitação (atributos `metadata.*` e `orq.metadata`) dos traces armazenados. |
| `variables` | Remove as variáveis de template e de ferramentas (atributos `orq.variables.*`) dos traces armazenados. |
| `all` | Atalho para `input`, `system`, `output`, `metadata` e `variables` em conjunto. |

## Cobertura

`security` é compatível com os endpoints de solicitação do AI Gateway: `responses`, `chat/completions`, `completions`, `embeddings`, `images/generations`, `images/variations`, `ocr`, `rerank`, `speech`, `transcriptions` e `translations`, e com `deployments/invoke`.

Três endpoints ignoram o campo: /classify não o aceita, e `images/edits` e `moderations` o aceitam sem aplicá-lo. Para mascarar traces de `/classify`, configure o plugin [Trace Scrubbing](/docs/pt-BR/ai-gateway/features/plugins/trace-scrubbing.md) no workspace ou em uma regra de roteamento. Nenhuma configuração mascara os traces de `images/edits`, `moderations` e das rotas WebSocket de `/responses` e `/responses/compact`, nem mesmo o Trace Scrubbing: os spans dessas rotas não registram opções de mascaramento, e por isso o mascaramento no momento da ingestão as ignora.

`security` não tem relação com o plugin [**PII Redaction**](/docs/pt-BR/ai-gateway/features/plugins/pii-redaction.md), que reescreve valores sensíveis na solicitação e na resposta em tempo real, nem com os [**Guardrails**](/docs/pt-BR/ai-gateway/configuration/guardrail-rules.md), que podem bloquear uma solicitação por completo. Ele altera apenas o que é gravado no armazenamento de traces; consulte [Comparação com o Trace Scrubbing](#comparison-to-trace-scrubbing) para conhecer o plugin que grava as mesmas máscaras a partir de um conjunto maior de lugares.


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