Skip to content

Policies Reference

Policies are reusable YAML definitions. The gateway evaluates them as a linear chain (global → product → user → API) on edge routes (/v1/api/..., /v1/webhooks/...).

Canonical reference: Gateway flow policies.

Implementation background: Trigger policy-chain redesign plan.


Policy definition

name: my-throttle
type: throttle          # throttle | headers | xml_json | oauth_outbound
direction: inbound      # inbound | outbound | both
config:
  max_requests: 60
  window_seconds: 60
  key_from: ip

Attach policies via ordered chains (not apply_to globs):

# Trigger API layer
invocation:
  policy_chain:
    - my-throttle
    - ref: my-headers
      direction: inbound

Product / user chains are edited in the dashboard (Admin → Policy layers). Global chains are maintained in git (flows/policy_chains/global/). API-specific chains are edited from the Triggers detail view.

If a chain step needs a local variation, use the dashboard Design action on that step:

  1. open the chain,
  2. choose Design,
  3. save the generated YAML under a new name,
  4. let the chain reference the derived policy.

Types (summary)

type Short description
throttle Fixed-window rate limit
headers Add / set / remove headers
xml_json Body XML ↔ JSON
oauth_outbound Client-credentials outbound token inject

Derived policies

Derived policies are normal named policy definitions that start from an existing base policy but are saved under a new name for a narrower scope such as:

  • one trigger / API,
  • one product,
  • one tenant onboarding flow.

Use them to avoid mutating a shared base policy that is still reused elsewhere.


Files

  • Definitions: flows/policies/*.yaml (uploaded to storage; optional POLICY_DIR disk seed)
  • Global chains: flows/policy_chains/global/{http,schedule,amqp}.yaml (uploaded to storage artifacts; gateway prefers these over Identity)
  • Product / user chains: identity service (dashboard UI)
flows/policies/
├── example-throttle-ip.yaml
├── example-headers-strip-secret.yaml
├── example-xml-to-json.yaml
├── example-json-to-xml.yaml
├── example-xml-json.yaml
├── erpnext-onramp-json-to-xml.yaml
└── example-oauth-outbound.yaml

flows/policy_chains/global/
├── http.yaml
├── schedule.yaml
└── amqp.yaml