Gateway Routing & Integration

Enable NjiraAI protection for your remote AI agents with a few lines of configuration. Point your agent clients to the Njira Gateway instead of the underlying provider API, allowing Njira to intercept, audit, and enforce policies on every request.

Integration Setup (Proxy Model)

The Gateway acts as a transparent proxy. You do not need to rewrite your agent workflows to use SDK verification methods.

Python (OpenAI Client)

from openai import OpenAI

client = OpenAI(
    # 1. Point to the Njira Gateway
    base_url="https://gateway.njira.ai/v1",
    # 2. Authenticate with your Njira Key
    api_key="nj_live_YOUR_KEY"
)

# 3. Make requests as normal. 
# Njira seamlessly intercepts, audits, and enforces policies inline.
response = client.chat.completions.create(
    model="gpt-5.2",
    messages=[{"role": "user", "content": "Hello world"}],
    extra_headers={
        "X-Njira-Tier": "standard",  
        "X-Tool-Name": "chat_interface" # CRITICAL: Essential for correct policy scoping
    }
)

TypeScript (OpenAI Client)

import OpenAI from 'openai';

const client = new OpenAI({
  baseURL: 'https://gateway.njira.ai/v1',
  apiKey: 'nj_live_YOUR_KEY',
});

// Requests are routed through Njira
const completion = await client.chat.completions.create({
  messages: [{ role: 'user', content: 'Hello world' }],
  model: 'gpt-5.2',
});

Advanced Routing Context

To ensure the correct policy evaluates your request, pass these operational headers. If omitted, the request falls back to environment defaults.

Header	Description	Example
X-Njira-Tier	Request specific model capability (fast, standard, strong).	fast
X-Policy-Id	Enforce a specific policy pack.	finance_guard
X-Tool-Name	Tag the source tool/agent for correct policy routing and audit logs.	search_tool
X-Tenant-Id	Override tenant context (requires Admin key).	tenant_xyz

API Contract: Handling Verdicts

The Gateway translates complex policy evaluations into standard HTTP status codes for your client to handle gracefully.

✅ 200 OK (ALLOW / MODIFY)

The request was deemed safe and successfully forwarded to the LLM.

If a MODIFY verdict occurred (e.g., PII redacted), the response content returned to your agent will transparently contain the safe, redacted/modified version. The agent rarely needs to know it was modified.

🚫 403 Forbidden (BLOCK)

The request violated a safety policy and was blocked before ever reaching the LLM.

Standard Response Body:

{
  "blocked": true,
  "reason": "PII_GUARD: Credit card number detected",
  "reason_code": "PII_DETECTED",
  "request_id": "req_123abc...",
  "verdict_urn": "urn:njira:verdict:block:..."
}

Triage: Debugging 403s & Shadow Mode

If your agent is receiving unexpected 403 Forbidden errors, follow this runbook:

1. Verify Policy Mode: Check the Njira Console to confirm if the applied policy is set to Active (active).
2. Review the Trace: Look up the request_id in the Traces UI to see exactly which rule fired.
3. Use Shadow Mode: If the policy is catching false positives, switch the policy binding mode from active to shadow.

Shadow Mode Headers

If a request hits a policy rule while in Shadow mode, Njira will never return a 403. Instead, it logs the block verdict but forwards the request, attaching warning headers to the successful response:

• X-Njira-Shadow-Verdict: BLOCK or MODIFY
• X-Njira-Shadow-Reason: The reason code (e.g., PROMPT_INJECTION)

You can inspect these headers in your staging environment to measure policy impact without breaking upstream traffic.