Skip to main content
Deploy the integrations/onyx FastAPI wrapper on any public HTTPS host. The AI Gateway calls it at llm_input / llm_output via the Custom Guardrail contract; the wrapper forwards extracted text to Onyx AI Guard /simple and returns verdict JSON on HTTP 200.

​
What is Onyx Security?

Onyx AI Guard is a SaaS platform for evaluating LLM prompts and responses against policies you configure in the Onyx console. You define Input- and Output-direction rules there; the wrapper does not embed policy logic. This integration uses Onyx’s /simple evaluate API: Auth to Onyx is the policy token in the URL path (ONYX_API_KEY) — there is no Authorization header on the Onyx call. The wrapper sends extracted text only: {"user_prompt": "..."} on input hooks and {"response": "..."} on output hooks (never both, never the whole gateway body). v1 is validate-only. When Onyx returns action: modify, these rails block instead of rewriting content.

​
How it works

  1. The AI Gateway POSTs an OpenAI-shaped requestBody (input) or requestBody + responseBody (output) to your wrapper URL.
  2. The wrapper extracts user/assistant text and calls Onyx /simple with your ONYX_API_KEY embedded in the evaluate URL.
  3. The wrapper returns HTTP 200 with a policy outcome in the body (see below). Infrastructure failures return HTTP 5xx.
Onyx policy decisions are always HTTP 200 with an action field. allow becomes {"verdict": true}; block and modify become {"verdict": false, "message": "..."} (block copy comes from Onyx’s custom_popup_message). Whether output blocking fires depends on your Onyx policy having an Output-direction rule.

​
Response contract

Policy blocks must use 2xx + verdict: false, not HTTP 4xx. See Custom guardrail response contract.

​
Wrapper endpoints

GET /health — health check. GET /debug/loaded-config — bearer-gated deploy verification. All POST routes expect Authorization: Bearer <WRAPPER_API_KEY> when the key is configured on the wrapper.

​
Prerequisites

  • Onyx policy token from the Onyx Security platform, plus Input / Output rules configured for your policies.
  • Public HTTPS URL for the deployed wrapper.
  • WRAPPER_API_KEY — shared secret; the AI Gateway sends it as Authorization: Bearer … when calling the wrapper.

​
Setup

1

Clone and configure

.env
Get ONYX_API_KEY in the Onyx platform. Default API base: https://ai-guard.onyx.security (override with ONYX_API_BASE if your tenant uses a different base).
2

Deploy the wrapper

Docker:
Local:
Put TLS in front of the service (load balancer, ingress, or your platform’s HTTPS URL). The AI Gateway must reach paths such as https://<host>/onyx-input.
Set TFY_WORKSPACE_FQN, TFY_PUBLIC_HOST, TFY_PUBLIC_PATH, and secret FQNs in .env. Create secrets onyx-api-key and wrapper-api-key under group onyx-guardrails-tfy in Platform → Secrets, then:
3

Register Custom Guardrail configs

AI Gateway → Guardrails → + Add New Guardrails Group → type Custom.
  • Group name: onyx-security
  • Add one config per wrapper path (two total), or start with input validate only.
Input validate example:Register the remaining config:Auth Data → Custom Bearer Auth works the same as Headers if you prefer not to set headers manually.
4

Attach to traffic

Model pin: AI Gateway → Models → <model> → Guardrails → attach group onyx-security.Per request — X-TFY-GUARDRAILS header, selector format <group>/<config-name>:
5

Verify

Call the wrapper directly:
Expect {"verdict": false, ...} when Onyx blocks, or {"verdict": true} when allowed (depends on your Onyx policy).
Confirm onyx_api_key_configured: true and the routes map.

​
Troubleshooting

​
Reference