Docs

Docs

Quick reference for integrating against the AI Security Gateway. The full operator-facing documentation lives alongside the backend repo.

Authentication

Every request requires an Authorization: Bearer <key> header. Keys use the prefixes sk-gw_live_… and sk-gw_test_…. Keys are validated against their SHA-256 hash on the server.

Request shape

POST / HTTP/1.1
Authorization: Bearer sk-gw_live_…
Content-Type: application/json

{
  "prompt": "…",
  "model": "openai/gpt-5.5",
  "stream": false
}

Response shape

HTTP/1.1 200 OK
x-request-id: 01HXYZ…
Content-Type: application/json

{
  "response": "…",
  "model": "openai/gpt-5.5",
  "meta": {
    "providerId": "litellm",
    "executionPath": "primary",
    "fallbackUsed": false,
    "entitiesDetected": 2,
    "latency": { "totalMs": 812, "maskingMs": 4, "providerMs": 800, "rehydrationMs": 2 }
  }
}

Streaming

Set stream: true and send Accept: text/event-stream. Streaming is artificial segmentation of the fully-rehydrated answer — never raw provider tokens — so masking guarantees are preserved.

data: {"chunk":"Hel"}

data: {"chunk":"lo, "}

data: {"chunk":"world."}

data: [DONE]

Errors

Errors carry a stable code and a generic message. Always log the x-request-id response header when reporting issues.

HTTP/1.1 4xx/5xx
{
  "error": { "code": "validation" | "unauthorized" | "rate_limited" |
                     "provider_timeout" | "provider_unavailable" |
                     "gateway_timeout" | "internal",
             "message": "human-readable, non-sensitive" }
}

Models

Send a real, provider-namespaced model ID — the same shape modern AI infrastructure tools use. Examples:

  • openai/gpt-5.5
  • openai/gpt-4o-mini
  • anthropic/claude-sonnet-4.5
  • google/gemini-2.5-pro

The accepted set is enforced server-side via the gateway's model catalog. Discover it with GET /models. Unknown or disabled IDs are rejected before any provider call. Provider API keys remain server-side; the frontend never calls a provider directly.

Raw prompt safety

  • • Prompts are masked deterministically before any provider call.
  • • Detected entity values are never returned to the client.
  • • Raw prompts are not logged — only safe metadata is emitted.
  • • This UI does not persist prompts; nothing is sent unless you click Send.