Gateway Governance

Provon applies two independent controls before or during a model call:

View as Markdown Open the plain-text version of this page.

On this page Browse sections

Usage limits decide whether the project API key may consume more requests, tokens, or cost.
Guardrails inspect the request or response and monitor, adjust, or block supported conditions.

Both controls produce structured project evidence: usage-policy events or guardrail trace events. Neither replaces application authorization or provider-side safety controls.

Provon Cloud managed targets also use an organization credit ledger. Credits pay for managed model execution; they are not a third project policy layer.

Usage Limits#

Usage limits are attached to the Provon project API key used by the application. They can apply to all Gateway requests on that key or to a specific model ID.

Supported metrics:

Metric	Modes	Typical use
Requests	Rate limit	Bound request throughput
Tokens	Rate limit or budget	Bound short-window throughput or total token volume
Cost	Budget	Bound estimated and actual USD spend

Supported windows are minute, hour, day, week, month, quarter, year, custom, and lifetime.

Configure A Limit#

In the Workbench:

Open API keys.
Expand the project key used by the workload.
Under Limits, select Add limit.
Choose metric, type, limit, period, and scope.
For a model-specific scope, enter the exact request model ID.
Save the limit and monitor used, reserved, remaining, and reset values.

Provon reserves estimated usage before routing, then settles successful requests against actual usage when the provider reports it. Failed requests release their reservation.

Rejection Contract#

When admission would exceed a policy, Gateway returns 429:

{
  "error": {
    "code": "gateway_budget_exceeded",
    "message": "Gateway budget exceeded",
    "reason": "cost_budget_exceeded",
    "policyId": "policy_123",
    "resetAt": "2026-08-02T00:00:00.000Z"
  }
}

Rate-limit rejections use rate_limit_exceeded. Responses include:

Retry-After
RateLimit-Limit
RateLimit-Remaining
RateLimit-Reset

Do not implement automatic retries for a cost or lifetime budget rejection. Retry only when the policy has a reset time and the workload can wait.

Cloud AI Gateway Credits#

Provon Cloud managed model targets use the organization's prepaid Cloud AI Gateway credits. This ledger is separate from project API-key usage limits:

credits pay for managed provider execution;
API-key limits bound one workload's requests, tokens, or cost;
BYOK requests use the upstream provider account instead of the Provon Cloud credit balance.

Provon reserves an estimated amount before a managed request and settles against actual model usage afterward. Insufficient balance returns 402:

{
  "error": {
    "code": "INSUFFICIENT_GATEWAY_CREDITS",
    "message": "organization does not have enough Cloud AI Gateway credits"
  }
}

Add credit under organization Billing. Do not retry until the balance changes or the request is moved intentionally to a BYOK target.

Guardrail Modes And Actions#

Guardrails are configured under Guardrails and run in priority order.

Workbench actions:

Action	Behavior
Monitor	Record the match and allow the exchange
Adjust	Redact supported sensitive content or lower supported request limits
Block	Reject the exchange with `409`

Start new rules with Monitor against representative traffic. Review the captured match evidence before switching to Adjust or Block.

Built-In Guardrails#

Data Protection#

Rule	Direction	Purpose
Personal data	Input and output	Detect email addresses and payment card numbers
Secrets and keys	Input and output	Detect API keys, access keys, JWTs, and private keys

These rules support monitoring, redaction through Adjust, and blocking. Match evidence stores categories and hashes rather than the matched secret value.

Tool Governance#

Rule	Purpose
Tool argument policy	Match risky tool names and argument conditions
Duplicate tool calls	Detect the same tool call repeated in a bounded message window
Duplicate tool output	Detect repeated consumption of the same tool result
Repeated tool errors	Detect repeated failures on the same tool path

Tool argument policies support wildcard tool names and optional argument-path predicates. Use them to enforce explicit application policy, not to infer business authorization from prompt text.

Context Budget#

Rule	Purpose
Conversation footprint	Cap message count, tool calls, and tool-definition size
Prompt token budget	Block requests over an estimated input-token limit
Response token budget	Monitor, cap, or block requested completion tokens

Input token checks are estimates. API-key token policies perform their own admission reservation and settle against provider-reported usage when available.

Guardrail Block Contract#

An enforced block returns 409:

{
  "error": {
    "message": "Provon Gateway blocked this exchange because a guardrail was triggered.",
    "type": "provon_gateway_guard",
    "code": "PROVON_GATEWAY_GUARD_TRIGGERED",
    "param": null,
    "retryable": false,
    "details": {
      "pluginId": "provon.guard.secret-leak",
      "action": "block",
      "direction": "input",
      "category": "openai_api_key"
    }
  }
}

The response includes:

x-provon-guard-triggered: true
x-provon-guard-plugin-id
x-provon-guard-action
x-provon-request-id

Do not retry the same blocked payload. Change the request or the project policy.

Tool Argument Policies#

Each Tool argument policy rule matches:

a tool-name pattern;
an optional argument field path;
an operator;
an optional comparison value;
an optional reason and category.

Supported operators include existence, equality, numeric comparison, string containment, prefix/suffix matching, and allow/deny list membership.

Example intent:

tool pattern: shell_*
field:        command
operator:     contains
value:        rm -rf
action:       Block

Keep tool authorization in the application. A Gateway guardrail is an additional policy boundary, not the source of user permissions.

Layering Controls#

Apply controls in this order:

Use application authentication and authorization for user actions.
Restrict project API-key capabilities and rotate keys independently.
Add API-key usage limits for hard resource boundaries.
Add guardrails for request, response, and tool-shape policy.
Restrict Provider Keys and model mappings to approved upstream targets.
Use Trace Capture to retain the evidence needed to audit decisions.

A request may be admitted by usage policy and still be blocked by a guardrail. A request may pass both and still fail provider authentication, capability checks, or upstream execution.

Security Guidance#

Give workloads Provon project keys, never upstream provider keys.
Use a separate project key per environment or application boundary.
Avoid raw secrets and unnecessary personal data in prompts and context headers.
Use Specific model mappings when a Provider Key must expose a strict allowlist.
Treat header overrides and custom upstream URLs as privileged configuration.
Review Provider Key, guardrail, and API-key changes as production policy changes.
Apply project telemetry retention to captured prompts, responses, and tool arguments.