Gateway Rules & Tenant Routing

A gateway rule is the unit of configuration that turns AgentWatch from a single endpoint into a policy surface: which upstream serves this call, under whose identity, with how much inspection, and what happens when it fails.

What is a gateway rule?

A rule binds a match to a mode and a target. Requests are matched on glob path patterns, headers, content type, size, source IP, and the resolved tenant; the mode decides how much AgentWatch interposes; the target names the upstream that actually serves it.

Rules are evaluated in priority order, and all matching rules are collected rather than stopping at the first, so a broad organizational rule and a narrow per-route override compose predictably.

What are the proxy modes?

Mode	What AgentWatch does
Passthrough	Forwards the request essentially untouched. Lowest latency; use where an upstream is already trusted and governed elsewhere
Proxied	Full request governance — authentication, DLP, budgets, rate limits, attribution and audit — then forwards
Enriched	As proxied, and augments the request before it leaves: injected context, tool definitions, or retrieval results
Post-process	As proxied, and inspects or transforms the response before returning it
Force model	As proxied, but the request is served by a model you choose, whatever model the caller asked for (per team, per employee, or per requested model)

The mode is visible on each route in the console as a pill, so the amount of inspection a route receives is legible at a glance rather than buried in configuration.

How does a tenant get resolved?

Attribution is what makes every other control meaningful, so AgentWatch resolves the tenant from the strongest available signal and never guesses:

An API key (Authorization: Bearer ak_…) — resolves directly to one employee or service account.
An identity header on a service key — attributes to the named employee inside that key’s organization. See delegated identity.
An enrollment token from the endpoint agent.
A mapped LAN IP, where an on-premises gateway sees each device’s pre-NAT address and an administrator has mapped it to a user.
A gateway IP allowlist — an administrator maps a corporate egress IP or CIDR to an organization. Organization-level only.
A registered DNS egress IP, for DNS-steered deployments with no per-request identity. Organization-level only.

Where two organizations could claim the same signal, the result is deliberately unattributed rather than arbitrary — a wrong attribution is worse than a missing one.

What can a rule do to a request?

Path and body transformation — rewrite paths, inject or strip fields, adapt a legacy client to a current upstream without touching the client.
Header policy — forward a safe allowlist of upstream headers, never credentials or cookies.
Per-route authentication — require a specific credential class on a given path.
Content-type filtering and size limits — refuse payload shapes a route should never receive.
Per-route IP allowlisting — restrict a sensitive route to known sources.
Per-route circuit breakers — isolate one failing upstream so it cannot degrade unrelated routes.

How do I create a rule?

Settings → Gateway Routes → Add route. A minimal proxied route needs a match pattern, a mode and an upstream:

Field	Example	Notes
Path pattern	`/v1/chat/completions` or `/v1/*`	Glob matching
Proxy mode	`proxied`	Start here; move to passthrough only when you want less inspection
Upstream	your provider or a self-hosted endpoint
Priority	`100`	Higher wins; all matching rules are collected in order

Save, then send one request and watch it land in Usage Insights → Audit Trail. The route’s mode is shown as a pill on the row, so you can confirm the request took the path you intended rather than a broader catch-all.

How do I check which rule a request matched?

Open the request in the audit trail — the row records the resolved route, the proxy mode, the upstream that served it, and the tenant it was attributed to. Two tags are worth knowing:

upstream_endpoint — which engine actually answered, when the upstream reports it. Pooled upstreams serve identical requests from different engines, so this is how you tell them apart.
identity_mode / identity_via — how the tenant was resolved.

If a request matched nothing you expected, the usual cause is a broader rule with a higher priority. Sort the route list by priority and read down.

How do I route by tenant?

Settings → Tenant Routing Rules. Rules are matched against the resolved tenant and composed with the gateway routes above, so an organization can be pinned to a specific upstream — a sovereignty requirement, a dedicated capacity pool, or a different model catalogue — without changing anything the client sends.

How do I always route a team or an employee to a specific model?

Use a Force model tenant routing rule (2.0.351). Every request the rule matches is served by the model you pick, whatever model the caller asked for — including auto (complexity routing). The model’s provider comes from your Model Catalog, so a team that keeps sending gpt-4o can be answered by Anthropic or Google Vertex: AgentWatch translates the request to that provider’s API. DLP, guardrails, budgets, rate limits and usage recording all still apply.

Settings → Tenant Routing Rules → Add Rule

Mode: Force Model (Always Use a Specific Model).
Target model: pick a model from your catalog. If the same model is registered under two providers, the list shows one entry per provider, so you choose the vendor as well as the model.
Scope — any combination, all of which must match:
- Teams: the teams the rule applies to (none selected = any team);
- Employees: specific people (none selected = anyone);
- Model (glob): only redirect some requested models, e.g. gpt-4o*. Leave empty to force everything the scope sends.
Priority: when several force rules match one request, the highest priority wins — so an employee-specific rule can override a team-wide one.

Over the API:

curl -X POST https://<your-gateway>/admin/tenant-routing-rules \
  -H "Authorization: Bearer $ADMIN_TOKEN" -H "Content-Type: application/json" \
  -d '{
    "name": "Engineering → Claude",
    "mode": "force_model",
    "priority": 10,
    "matchTeamIds": "[\"<engineering-team-id>\"]",
    "matchModel": "gpt-4o*",
    "modeConfig": "{\"targetModel\": \"claude-sonnet-4-5\"}"
  }'

Verify it. Send a request as someone in that team asking for gpt-4o:

the response carries x-agentwatch-forced-model: gpt-4o->claude-sonnet-4-5;
in Usage Insights the row shows the served model and provider, tagged requested_model: gpt-4o, routed_by: force_rule and forced_model_rule: Engineering → Claude;
Observe Platform → AI → Agents topology counts it under forced by rule in the Routing column.

How it interacts with model access. The target is not checked against the team’s model-access list: the rule is the access decision, and refusing an admin-chosen model with “not available to your team” would blame the caller for the admin’s rule. A passthrough rule that matches the same request still wins, because passthrough skips the pipeline entirely.

Symptom	Cause	Fix
`400 Force-model mode requires modeConfig.targetModel` when saving	No target chosen	Pick a target model
Requests are not redirected	The scope does not match (wrong team, or a Model glob that excludes what they send)	Clear the Model glob, check the team/employee selection; rules apply within ~30 s
`400 … not available in your organization` naming the target	The target has no provider that can serve it in this organization	Add or fix the provider for that model in Model Catalog
A different force rule applied	Another matching rule has a higher priority	Adjust priorities

Verifying and rolling back

A rule change applies to the next request; settings reads are cached for a few seconds, so allow a moment rather than restarting anything. Every change is written to Settings → Audit Logs with a per-field before-and-after diff, so rolling back means reading the diff and restoring the previous values.

Test a new route against one key before making it broad: give the route a narrow path or an IP allowlist, confirm the audit trail shows what you expect, then widen it.

How do rules interact with model access?

A rule decides where a request goes; the model catalog decides what a tenant may ask for. Both apply. A tenant may only use models exposed to their organization and team, and the catalog either allows a model or it does not — consistently, regardless of which protocol asked. An alias configured for an organization resolves to the underlying upstream model before the request leaves.

Can a request be routed by cost or content?

Yes. Routing modes compose with rules: semantic routing by request topic, weighted splits across model variants, round-robin and least-loaded across API keys, cost-optimized selection of the cheapest model meeting the required capabilities, priority lanes for latency-sensitive traffic, and health-monitored failover. The router will not select a model whose context window cannot hold the request.

What happens when an upstream misbehaves?

Failures are classified rather than flattened, because the status a client receives determines whether it retries:

A context-length overflow returns 400 with an actionable message, not a 500 — so SDKs treat it as terminal instead of retrying a request guaranteed to fail.
Provider rate limits surface as 429 with Retry-After, so well-behaved SDKs back off.
Transient upstream faults stay retryable, and circuit breakers trip per route and per provider.
Failover across providers (2.0.351). When complexity routing’s Failover strategy moves to the next model in a tier, it now uses that model’s own provider and key. Before 2.0.351 it kept the failed model’s provider, so a tier such as gpt-4o, claude-sonnet-4-5 sent Claude’s model id to OpenAI. A model in the chain with no provider in your organization is skipped rather than sent somewhere that cannot serve it.
Budget, plan-limit and rate-limit rejections are recorded as blocked usage rows with a reason code, so a spend report can show refusals beside guardrail blocks.

Where are rules configured?

In the console under gateway routes, or over the admin API for infrastructure-as-code. Rule changes take effect on the next request; settings reads are cached briefly, so a change is live within seconds rather than requiring a restart. Every change is recorded in the audit log with a per-field before-and-after diff.

Sources and references

Per-request employee attribution on a shared credential: Delegated identity and Auto Create Users.
Provider selection, caching and failover: LLM gateway and routing.
What is inspected in proxied and post-process modes: Data protection and guardrails.
Budgets and quotas applied to matched traffic: Governance and cost control.