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

# Mask sensitive content in traces

> Control which request and response content gets written to stored traces with the security parameter on the AI Gateway, without changing live output.

**Use Cases**

* Keeping system prompts out of stored traces while still tracing the request.
* Excluding user-submitted content from logs to meet data-handling requirements.
* Redacting model output from traces without changing what the caller receives.

The `security` parameter controls what gets written to stored traces. It does not change the live request or response: the caller always receives the full, unmasked output. Only the copy persisted to trace storage is affected.

<Warning>
  Masking `input`, `output`, `system`, or `all` with `security.mask` only affects the copy of the request written to stored traces. **The full, unmasked payload is still sent to the model provider.** To prevent PII from leaving in the live request or response, enable the [**PII Redaction**](/ai-gateway/features/plugins/pii-redaction) plugin.
</Warning>

<Note>
  `security` is set per request. There is no workspace, project, or API-key default, so a request that sends no `security` block is traced in full unless a workspace-level mask applies. To mask every request without repeating the field, enable [Trace Scrubbing](/ai-gateway/features/plugins/trace-scrubbing) for the workspace, subject to the routes listed under [Coverage](#coverage). To attach the field automatically instead, set it as a default on the SDK client.
</Note>

## Comparison to Trace Scrubbing

**Trace Data Masking** (this page) and [Trace Scrubbing](/ai-gateway/features/plugins/trace-scrubbing) both decide what the **AI Gateway** writes to a stored trace. They mask the same fields with the same code, so what differs is not what gets masked but where the mask is set and who can change it.

**What is the same**

* Both accept `input`, `output`, `system`, `metadata`, `variables`, or `all`.
* Both blank or remove those fields from the stored trace only. The live request, the response, the payload the provider receives, and the data [**Guardrails**](/ai-gateway/configuration/guardrail-rules) and [**Evaluators**](/ai-studio/optimize/evaluators) check are untouched.
* A request that sends both is merged: the masks add up, and neither side removes a mask the other set.

**What differs**

| | `security.mask` on a request | `trace_scrubbing` plugin |
| - | - | - |
| Where it is set | In the request's `security` block | In the request's `plugins` array, on a [routing rule](/ai-gateway/configuration/routing-rules#plugins), on an [MCP gateway](/ai-gateway/mcp-portal/mcp-gateways), or for the whole workspace under [**Settings** > **Plugins**](/ai-gateway/features/plugins/trace-scrubbing#enable-for-a-workspace) |
| Applies without the caller sending it | No. A request that omits the field is traced in full unless the workspace, a rule, or a gateway adds masks | Yes for the workspace, routing-rule, and MCP-gateway placements; a request-scoped `plugins` entry still needs the caller |
| Can a request loosen it | Not applicable: the caller sets it, so it can change or drop it per request | No. A request can add masks but cannot remove one set by the workspace, a rule, or a gateway |
| Endpoints it reaches | Every endpoint where it is applied, including `deployments/invoke`. [/classify](/ai-gateway/features/classify) ignores it, and `images/edits` and `moderations` accept it without applying it | The same endpoints, plus `/classify` and deployment invokes when set on the workspace or a routing rule, and the tool-call traces an MCP gateway stores; `images/edits`, `moderations`, and the `/responses` WebSocket and `/responses/compact` routes traces stay unmasked |
| Empty selection | Allowed, and masks nothing | A request entry with no `mask` values is accepted and masks nothing; a routing-rule or MCP-gateway placement rejects one. A workspace toggle with no values selected masks everything |

**Which to use**: `security.mask` suits a caller protecting its own traffic, at the cost of sending the field on every request. `trace_scrubbing` suits a policy that must hold for everyone, because an admin sets it once for the workspace, a rule, or a gateway and no caller can opt out.

## Quick Start

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl -X POST https://my.orq.ai/v3/router/responses \
    -H "Authorization: Bearer $ORQ_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.ORQ_API_KEY,
    baseURL: "https://my.orq.ai/v3/router",
  });

  const response = await client.responses.create({
    model: "openai/gpt-5.4-mini",
    input: "Summarize AI trends for 2025",
    // @ts-ignore - orq.ai 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("ORQ_API_KEY"),
      base_url="https://my.orq.ai/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 - orq.ai extension
    security: { mask: ["input"] },
  });
  ```
</CodeGroup>

## Configuration

| Parameter | Type | Required | Description |
| - | - | - | - |
| `mask` | string\[] | No | Which content to mask in stored traces: `input`, `output`, `system`, `metadata`, `variables`, or `all`. |

An unrecognized value in `mask` is rejected with a 400 error.

## What each value masks

| Value | Effect on stored traces |
| - | - |
| `input` | Blanks user message content, and (on tool spans) the tool-call arguments. |
| `system` | Blanks system and developer message content, and (on tool spans) the resolved tool variables. Also strips `description` and the parameter schema (`parameters` or `input_schema`) from tool definitions, keeping only name and type. |
| `output` | Blanks assistant message content, and (on tool spans) the tool-call result. |
| `metadata` | Removes custom request metadata (`metadata.*` and `orq.metadata` attributes) from stored traces. |
| `variables` | Removes template and tool variables (`orq.variables.*` attributes) from stored traces. |
| `all` | Shorthand for `input`, `system`, `output`, `metadata`, and `variables` together. |

## Coverage

`security` is supported on the AI Gateway's request endpoints: `responses`, `chat/completions`, `completions`, `embeddings`, `images/generations`, `images/variations`, `ocr`, `rerank`, `speech`, `transcriptions`, and `translations`, and on `deployments/invoke`.

Three endpoints ignore the field: [/classify](/ai-gateway/features/classify) does not accept it, and `images/edits` and `moderations` accept it without applying it. To mask `/classify` traces, set the [Trace Scrubbing](/ai-gateway/features/plugins/trace-scrubbing) plugin on the workspace or on a routing rule. No placement masks `images/edits`, `moderations`, and the `/responses` WebSocket and `/responses/compact` routes traces, Trace Scrubbing included: their spans record no masking options, so ingest-time masking passes over them.

`security` is unrelated to the [**PII Redaction**](/ai-gateway/features/plugins/pii-redaction) plugin, which rewrites sensitive values in the live request and response, and to [**Guardrails**](/ai-gateway/configuration/guardrail-rules), which can block a request outright. It changes only what is written to trace storage; see [Comparison to Trace Scrubbing](#comparison-to-trace-scrubbing) for the plugin that writes the same masks from a wider set of places.


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