Skip to content

Policies Reference

Policies are YAML files that the gateway evaluates before a workflow run is forwarded to the orchestrator (via edge routes: /v1/api/..., /v1/webhooks/...).

Canonical technical reference (types, fields, environment variables, policy bindings, behaviour in code): Gateway flow policies.

This page stays a short flows-focused summary with examples; if anything conflicts, the engine reference wins.

Policy model

name: my-policy              # recommended; required for gateway_policy_bindings on the trigger
type: <policy-type>
apply_to:
  - "order-*"               # fnmatch pattern or exact workflow name
  - "billing-invoice"
apply_to_triggers:
  - http                     # typically http at the gateway edge; see canonical doc for "*"

Evaluation runs for every policy whose apply_to and apply_to_triggers match—processing order follows policy filename (alphabetically under POLICY_DIR). There is no separate global step-by-step pipeline across policies; do not combine conflicting rules unless you separate scopes with apply_to.

Policy types (summary)

type Short description
required_headers Mandatory HTTP headers; on_violation: reject → 400, log → log only
oauth_inbound Bearer token introspection against an IdP (introspection_url, optional required_scopes)
rate_limit_product Quota via identity/product model (fallback_product, etc.)
transform Declarative inbound / outbound / on_error blocks—the gateway collects specs; see canonical doc for wiring transforms

See Gateway flow policies for all fields and boundaries (e.g. /v1/run does not use flow policies, optional gateway_policy_bindings on the invocation).

Policy files

  • Repo location: flows/policies/*.yaml; runtime: environment variable POLICY_DIR (default /app/flows/policies).
  • Cache: POLICY_CACHE_TTL_SECONDS (default 30 seconds).
flows/policies/
├── global-headers.yaml
├── partner-oauth.yaml
├── rate-limits.yaml
└── order-transform.yaml

Examples in the repository:

  • flows/policies/example-require-headers.yaml
  • flows/policies/example-oauth-inbound.yaml
  • flows/policies/example-transform-policy.yaml
  • flows/policies/example-rate-limit-product.yaml

Operational guidance

  • Start in non-production and monitor rejected requests.
  • Version and review policies like code.
  • Use on_violation: log during rollout to audit without blocking.
  • Glob patterns use Python fnmatch (e.g. order-*).

See also