> ## Documentation Index
> Fetch the complete documentation index at: https://www.truefoundry.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Noma Security
> Configure Noma AI-DR in TrueFoundry AI Gateway to allow, alert, block, or mask unsafe prompt, response, and tool content.
Use [Noma Security](https://noma.security/) with TrueFoundry AI Gateway to apply AI Detection and Response (AI-DR) policies to prompts, responses, and tool content. Depending on the Runtime Protection profile assigned in Noma, the guardrail can allow, alert on, block, or mask content.
## How the integration works
TrueFoundry sends the complete provider-native payload to Noma's dedicated TrueFoundry guardrail endpoint. Noma evaluates it using the Runtime Protection profile associated with the configured **Application ID**.
The integration supports:
* OpenAI Chat Completions requests and completed responses
* OpenAI Responses API requests and completed responses
* Anthropic Messages requests
* Provider-native tool definitions, tool calls, tool results, metadata, and other payload fields
Response evaluation and mutation require a completed, non-streaming response.
## Prerequisites
Before you begin, obtain a Noma scoped access token with the `truefoundry_guardrail` scope. This integration uses the token directly and does not use Noma's OAuth client-credentials flow.
## Add the Noma Security guardrail
In TrueFoundry, go to **AI Gateway → Guardrails**, create or open a guardrail group, and select **Noma Security** under **External Providers**.
Complete the Noma Security configuration:
* **Name**: Enter a name such as `noma`.
* **Description**: Optionally describe the policies applied by this integration.
* **Operation**: Select **Mutate**. This lets TrueFoundry apply complete masked request or response payloads returned by Noma, in addition to enforcing block decisions.
* **Priority**: Set the execution order when the hook has multiple mutate guardrails. Mutate guardrails run sequentially.
* **Enforcing Strategy**:
* **Enforce** blocks the request when Noma reports a policy violation or the Noma call fails.
* **Enforce But Ignore On Error** enforces policy violations but allows the request to continue when the Noma call fails.
* **Audit** records violations without blocking the request.
* **API Key**: Enter the Noma scoped access token.
Configure these optional fields:
* **Base URL**: Leave empty to use `https://api.noma.security`. You can instead use a Noma regional endpoint:
* US: `https://api.us2.noma.security`
* EU: `https://api.eu.noma.security`
* AP: `https://api.ap.noma.security`
* **Application ID**: Stable identifier used to select and attribute the Noma Runtime Protection profile. The default is `truefoundry`.
* **Session ID**: Fixed session identifier sent to Noma for session attribution. Leave it empty to send no session id at all — there is no fallback value.
Use a different Application ID when different applications need different Noma profiles. Keep the value stable across requests for the same application.
There is no **User ID** field. The Noma user id is derived from the authenticated caller: the user's email for a Personal Access Token, or the account name for a virtual account. If a request reaches the guardrail without an identifiable caller, no user id is sent.
Save the guardrail group, then attach the integration to the required LLM input, LLM output, or MCP tool hooks through a [guardrail policy](/docs/ai-gateway/guardrails-configuration).
Keep the Noma access token in TrueFoundry. Do not include it in client code, request metadata, or model payloads.
## Request metadata and attribution
TrueFoundry forwards this identity context to Noma with each evaluation:
* The configured **Application ID**, defaulting to `truefoundry`
* The configured **Session ID**, when set
* The **authenticated caller** — the user's email or the virtual account's name — as the Noma user id, when identifiable
* A unique identifier for the Noma call itself
TrueFoundry request metadata sent in `X-TFY-METADATA` is **not** forwarded to Noma. Only the identity fields above and the request or response payload being scanned are sent. If Noma policies need to key off an application or environment, encode it in the Application ID or Session ID rather than in request metadata.
Noma uses this identity for session attribution, detections, and policy analysis. The same fields are sent on every hook — LLM input and output, and MCP tool pre- and post-invocation — and are identical for Validate and Mutate operations.
## Decision and mutation behavior
Noma's Runtime Protection profile determines the result:
| Noma decision | Noma response | TrueFoundry behavior |
| - | - | - |
| Allow | HTTP `200` with JSON `null` | Forwards the original provider payload unchanged |
| Alert | HTTP `200` with JSON `null` | Forwards the original payload and records the detection in Noma |
| Mask | HTTP `200` with a JSON object | Replaces the original provider request or response with the complete object returned by Noma |
| Block | HTTP `400` with `{"message":"Content blocked by guardrail"}` | Stops the inference |
Only the exact `Content blocked by guardrail` response is treated as a Noma policy decision. Other `400` responses indicate an invalid or unsupported payload and are handled as integration errors according to the configured Enforcing Strategy.
## Verify the integration
After applying the guardrail to a model, test these paths:
1. Send a clean prompt and confirm the model request succeeds unchanged.
2. Send content covered by an alert profile and confirm the request succeeds and a detection appears under **Runtime Protection → Sessions** in Noma.
3. Send content covered by a block profile and confirm TrueFoundry stops the inference.
4. If masking is enabled, send synthetic sensitive data and confirm the model receives Noma's masked provider payload.
Use unique requests for each test while keeping the configured Application ID stable for the selected Noma profile. You can inspect guardrail execution, mutations, and downstream model status in **AI Gateway → Monitor → Request Traces**.
## Reference
* [Noma Security](https://noma.security/) — AI security platform overview
* [Noma AI Runtime Protection](https://noma.security/platform/runtime-protection/) — AI-DR capabilities for prompts, responses, and tool calls
* [TrueFoundry guardrails overview](/docs/ai-gateway/guardrails-overview)
* [Configure guardrail policies](/docs/ai-gateway/guardrails-configuration)
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.