Gateway Policies

Policies such as control, protection, and mediation executable pipeline

Central principle

A policy is infrastructure code: order, dependencies, side effects and failure handling determine its behavior.

In-depth edition - study material and professional reference

radio_button_unchecked Chapter presentation

The previous chapter introduced API Gateway as a specialized intermediary that terminates connections, applies controls, selects routes, and creates a new relationship with the backend. This chapter delves into the mechanism that makes this behavior programmable: gateway policies. A policy represents a decision or transformation unit executed at a certain point in the flow. Authentication, token validation, rate limiting, caching, payload transformation, routing and observability can be implemented by chained policies.

In a simple demonstration, policies look like independent blocks that can be dragged or written in XML, YAML, JSON, or a graphical language. In production, however, they form a distributed program. The order changes the result; one policy produces context consumed by the next; external calls introduce latency and availability; reading the body can consume streams; retries can multiply effects; and a failure can terminate the request before the backend is reached.

Policies are also part of the security model. A precedence error can allow traffic before authorization, log tokens in the clear, apply quota to the wrong identifier, or transform a signed message and invalidate its integrity. Therefore, policy design requires the same care as software engineering: clear responsibilities, testing, review, versioning, observability, rollback and change control.

The goal of this chapter is to build a product-agnostic mental model and relate it to implementations such as Axway API Gateway, Azure API Management, and filter-based proxies. In the end, the reader should be able to design a pipeline, justify its order, predict failure effects, identify external dependencies and diagnose in which policy a call was changed or rejected.

How to study this chapter

For each policy, record five elements: input, execution condition, effect, produced state and failure behavior. Then analyze how it interacts with previous and subsequent policies. This method turns a visual string into a comprehensible program.

Learning Objectives

• Explain policy as an executable unit of decision, control or transformation in the data plan.
• Distinguish inbound , backend, outbound and on-error sections, recognizing equivalents in different products.
• Analyze order, dependencies, short-circuit, context variables and side effects.
• Design authentication, authorization, validation, throttling , caching, transformation and routing policies.
• Understand retries, timeouts, circuit breaker , fallback and idempotence.
• Recognize risks of body reading, buffering, header manipulation and external calls.
• Build consistent error handling without hiding the technical cause.
• Apply logs, metrics, traces, correlation and auditing at the policy level.
• Organize reuse, inheritance, scopes, fragments, templates and parameters.
• Apply CI/CD, testing, review, segregation of duties, and rollback to gateway policies.

Chapter structure

• 22.1 What is a policy
• 22.2 Execution model and sections
• 22.3 Order, context and short-circuit
• 22.4 Scopes, inheritance and precedence
• 22.5 Authentication and identity policies
• 22.6 Authorization and external decisions
• 22.7 Validation of messages and contracts
• 22.8 Rate limiting, quotas and throttling
• 22.9 Transformation of headers, URL and payload
• 22.10 Routing and backend selection
• 22.11 Cache and coherence
• 22.12 Resilience and external calls
• 22.13 Error handling
• 22.14 Observability and auditing
• 22.15 Reuse and governance
• 22.16 Testing, CI/CD and troubleshooting
• Summary, checklist, exercises, glossary and references

radio_button_unchecked 22.1 What is a policy

A policy is a rule executed by the gateway on a request, response, connection or context . It can observe data, produce variables, allow or deny continuity, modify the message, call an external service, change the destination or generate a response without forwarding the request. In graphic products, the policy can be represented by connected filters; on declarative platforms, by configuration elements executed in sequence.

Policy should not be confused with abstract organizational policy. A rule like “only partner applications with an active contract can access the API” is a business or security policy. To execute it, the gateway can combine several technical policies: validate certificate, extract client_id, consult a PDP , check contract status, record decision and apply quota. The pipeline is the operational implementation of the rule.

Policies can be local, when they only use the context already available, or remote, when they consult IdP, introspection endpoint, bank, cache, authorization service or anti-fraud system. Remote polices increase power, but also introduce network dependency, timeout, retry, authentication between components and the risk of cascading unavailability.

radio_button_unchecked 22.2 Execution model and sections

Gateway platforms often divide the pipeline into phases. In inbound , the request is received and can be authenticated, validated, limited and transformed. In the backend phase, the gateway prepares and executes the call to the upstream. In outbound , it processes the response, removes data, adds headers, normalizes errors or stores cache. On failures, an on-error section or equivalent produces specific handling.

These phases are logical, not universal. One product can represent everything as a tree of filters, another as declarative sections, and another as HTTP filters connected to the listener. The architect must map the concept to the product without assuming perfect equivalence. The decisive point is knowing where the message is, whether the backend has already been called and what context remains available.

A policy can short-circuit and produce a response immediately. An invalid_token validation may return 401; an exceeded rate limit may return 429; a cache hit can return 200 without accessing the backend. Therefore, “the gateway received the call” does not mean that the backend was called. Logs from each phase need to make this decision visible.

radio_button_unchecked 22.3 Order, context and short-circuit

The order of execution is part of the semantics. Correlating the request before any rejection ensures that 401 and 429 responses also have request IDs. Authenticate before authorizing provides identity to the decision policy. Validating payload size before parsing avoids wasting CPU on abusive messages. Applying transformation before validation may be correct when the gateway normalizes a legacy format, but dangerous when it hides invalid input.

Policies exchange information through an execution context . This context can contain method, URL, headers, certificate, identity, variables, partial response, current error and metrics. Variables must have predictable names, a known type, and a documented scope. Reusing generic names like token, user or result in different fragments increases collisions and makes troubleshooting difficult.

Short-circuit is useful to reject early and save backend. However, the response needs to preserve observability, CORS when applicable, security headers and error format. Otherwise, calls rejected by the gateway behave differently than responses produced by the backend, confusing consumers and monitors.

Review question

If two policies are swapped, does the behavior change? If the answer is yes, this dependency must be documented and covered by testing. If the team doesn't know how to respond, the pipeline is not yet sufficiently understood.

radio_button_unchecked 22.4 Scopes, inheritance and precedence

Policies can be applied at different scopes: global, workspace, product, API, version, operation or specific instance. Broad scopes reduce duplication and ensure minimal controls, while narrow scopes allow specialized behavior. Risk appears when inheritance and precedence are not clear. An API may imagine that it has replaced a global policy when, in reality, it has just added another step.

Inheritance should be used for enterprise invariants: correlation, minimal headers, secret protection, essential logs, and mandatory controls. Business rules, specific routing and payload transformation typically belong to scopes closer to the API. The more business logic is placed globally, the greater the blast radius of a change.

Fragments and templates need to receive explicit parameters and avoid hidden dependencies on global variables. A change to a reused fragment can affect hundreds of APIs. Therefore, references must be versioned, tested by consumers and released gradually.

radio_button_unchecked 22.5 Authentication and identity policies

Authentication polices verify the presented credential and establish a trusted identity. This may involve API key, Basic Auth, client certificate, opaque access token, JWT or custom credentials. The result should not just be a boolean. The pipeline needs to produce normalized context : subject, client, issuer, audience, scopes, authentication method and assurance level.

In JWT validation, the policy must check signature, allowed algorithm, issuer, audience, expiration and required claims. Just decoding the token does not authenticate anyone. For opaque tokens, the policy can query introspection, with controlled caching and short timeout. For mTLS, the identity must not be derived solely from the CN without trust rules, SAN, and certificate chain.

Credentials should not be logged. When the gateway propagates identity to the backend via headers, it must remove equivalent headers sent by the consumer and write trusted values. The backend needs to accept these headers only from an authenticated network or gateway identity; otherwise, the consumer may forge the context .

Pseudocode - identity establishment and propagation

# Conceptual authentication flow remove_header_unreliable("X-Authenticated-Subject") credential = extract_credential(request) identity = validate(credential) if identity.invalida: return 401 context .subject = identity.subject context .client_id = identity.client_id add_header_backend("X-Authenticated-Subject", context .subject)

radio_button_unchecked 22.6 Authorization and external decisions

Authorization responds to whether the identity can perform the action on the resource in that context . Simple policies check scopes, roles or claims. Advanced cases query a Policy Decision Point, sending attributes of the subject, resource, action and environment. The gateway policy acts as a PEP : collects data, requests a decision, applies allow or deny and records evidence.

An external authorization call needs a stable contract, mutual authentication, timeout, circuit breaker and fail-open or fail-closed decision. For sensitive operations, fail-closed is the safe rule: if the PDP does not respond, access is denied. For non-critical telemetry, a policy may fail in a degraded way. This choice should be explicit and risk-approved, not accidentally decided by the tool's default behavior.

Decisions can be cached when attributes and validity allow. The cache key must include all elements that influence the decision. Caching only by user, ignoring resource, action or tenant, creates incorrect authorization. Invalidation also needs to consider change of role, revocation and termination of contract.

radio_button_unchecked 22.7 Validation of messages and contracts

Validation policies check method, Content-Type, size, schema, mandatory fields, parameters and restrictions. Early validation protects the backend and makes errors consistent. OpenAPI can provide part of the contract, but not every business rule must be transferred to the gateway. Complex validations, dependent on the state of the domain, belong to the responsible service.

Validating JSON or XML requires parsing and can consume memory. The gateway must impose a size limit before loading the body. On large streams, uploads and downloads, complete buffering can destroy performance. Policies that need to read the body must document whether they preserve the stream for later steps.

Validation in detect or log-only mode can help with migration, but should not become a permanent state. If the organization collects violations without blocking, it needs time and criteria to activate enforcement. Otherwise, the declared contract and actual traffic continue to diverge.

radio_button_unchecked 22.8 Rate limiting, quotas and throttling

Rate limiting restricts the number of events in a window; quota controls consumption accumulated over a longer period; throttling regulates speed or concurrency to protect capacity. Although terms vary between products, the policy needs to define unit, key, algorithm, window, response and distributed scope.

The position in the pipeline changes the objective. Limiting by IP before authentication reduces volumetric attacks. Limit by client_id after authentication applies commercial plan or contract. Limiting by operation protects expensive endpoints. Many platforms combine layers, but each counter increases cost and dependency on shared state.

On distributed gateways, local counters may allow the aggregate total to exceed the limit. Global counters require shared service and introduce latency. The architecture must declare whether the limit is approximate or strict. The 429 response should include guidance such as Retry-After when possible and not reveal unnecessary internal details.

Further deepening

Chapter 27 will be dedicated to Rate Limiting, Quotas and Throttling . Here, the focus is on understanding how these policies participate in the pipeline and interact with identity, distributed state, and error handling.

radio_button_unchecked 22.9 Transformation of headers, URL and payload

Transformation policies adapt consumers and backends: add or remove headers, rewrite paths, convert query parameters, change Content-Type or transform JSON and XML. They are useful for modernizing legacies and maintaining stable contracts, but they can create invisible coupling. The backend now depends on a message that no consumer sends directly.

Security and identity headers require special rules. The gateway must remove untrusted values before inserting its own. Hop-by-hop headers should not be propagated as end-to-end headers. Host and SNI need to be handled consciously, as an incorrect rewrite may reach the wrong virtual host or cause certificate failure.

Payload transformations cost CPU and memory and can change signature, hash or idempotency key. If a message is signed by the consumer, any change invalidates the signature, unless the model foresees a new signature by the gateway. Transformations must be small, tested and observable; Extensive business logic at the gateway becomes an integration monolith that is difficult to evolve.

Conceptual example of declarative policies

< inbound > <set-header name="X-Correlation-ID" exists-action="skip"> <value>@(Guid.NewGuid().ToString())</value> </set-header> <rewrite-uri template="/clientes/{id}" /> <set-backend-service base-url="https://backend.interno" /> </ inbound >

radio_button_unchecked 22.10 Routing and backend selection

Routing policies choose backend, version, region, cluster, tenant or canary implementation. The decision can use path, header, claim, weight, health, latency or external configuration. Routing is different from authorization: a consumer can be authorized and still be sent to the wrong backend if precedence rules are ambiguous.

Canary and blue-green require affinity when the experience needs to remain consistent across calls. The gateway must record which variant was chosen and propagate identifier for tracing. Cross-region fallback needs to consider data residency, consistency, and idempotence. Automatically sending a write to another region after timeout can duplicate transactions.

Backend discovery may depend on DNS, service registry, or static configuration. Policies should not perform customized resolution for each request without caching and limits. The control plane must distribute destinations securely, while the data plane continues to process traffic even during temporary unavailability of the management plane.

radio_button_unchecked 22.11 Cache and coherence

Cache policies can reduce latency and backend load, but require understanding HTTP semantics and the data contract. The key must include method, normalized URI, and all relevant variations such as tenant, language, Accept, and authorization. Caching private response without separating consumers can cause serious leakage.

The gateway must respect Cache-Control, Vary, and invalidation rules when applicable. In authenticated APIs, the cache often needs to be private on a per-consumer basis or limited to truly public data. A cache hit should also produce logs and metrics; otherwise, the backend will look healthy because it receives less traffic, while consumers may be receiving stale content.

Cache does not universally fix slow backend. It changes consistency and behavior on failure. Stale-while-revalidate and fallback with old data may be valid for catalog, but inappropriate for balance or authorization. The policy needs to reflect the criticality of the domain.

radio_button_unchecked 22.12 Resilience and external calls

Timeout limits how long the gateway waits. Retry repeats an operation under specific conditions. Circuit breaker stops calls when the dependency has persistent failures. Fallback produces alternative response or uses another source. These mechanisms must be designed in conjunction with the total latency budget and idempotence of the method.

Retrying GET can be safe in many cases, but not automatically. A poorly designed GET can trigger side effects. Retry in POST can duplicate transactions without key idempotency and backend deduplication. It is also necessary to avoid multiplication between layers: client, gateway, mesh and backend can repeat simultaneously and turn a small failure into a storm.

Auxiliary calls made by policies - introspection, PDP , vault, anti-fraud - need smaller timeouts than the main budget. The gateway must distinguish business API failure from policy dependency failure. Without this distinction, an unavailability of the authorization service appears as a generic 500 and hinders operational response.

radio_button_unchecked 22.13 Error handling and standardized responses

Error policies convert internal failures into stable consumer responses. They must preserve the correct status, a business or platform error code, secure message, correlation ID, and documentation. The treatment cannot transform any failure into 200 nor hide the difference between authentication, authorization, limitation, timeout and unavailability.

A standardized response should avoid sensitive details such as stack trace, cluster name, file path, SQL, internal endpoint, or token content. At the same time, internal logs need to maintain the cause, policy, time and dependency involved. The consumer receives a safe view; the operation receives sufficient evidence.

Errors produced before the backend need to apply common headers, including CORS when necessary. Otherwise, the browser may hide the real error due to CORS failure. It is also important to prevent the error policy from failing when trying to read variables that were not created, generating a second exception that masks the first.

Standardized error response example
{
  "type": "https://api.empresa.example/errors/rate-limit",
  "title": "Request limit exceeded",
  "status": 429,
  "detail": "Try again after the indicated period.",
  "correlationId": "8f4d9c2a-..."
}

radio_button_unchecked 22.14 Observability and audit at policy level

Gateway observability needs to answer which policies they executed, how much time they took, and what decision they made. An access log with status and total duration is necessary, but insufficient. Remote police must measure latency and results. Rate limit must register anonymized key and counter. Routing must register selected backend. Authentication must record method and reason for failure without exposing credentials.

Distributed tracing must create or preserve trace context and generate spans for backend calls and policy dependencies. A transformation policy can add useful attributes, but cardinality needs to be controlled. client_id, API, operation, version and result are useful dimensions; Full payload and personal identifiers should not become metric labels.

Audit differs from operational log. It records administrative changes and sensitive decisions with integrity, retention and controlled access. Who changed a global policy, who approved it, which version was deployed, and which APIs were affected are essential information for investigation and compliance.

radio_button_unchecked 22.15 Reuse, fragments and governance

Reuse reduces duplication, but needs to be controlled as a library. Fragments must have a contract, version, owner, examples, tests and changelog. A JWT validation fragment , for example, must declare issuers, audiences, algorithms, produced variables and error format. Without this, each API becomes dependent on implicit behavior.

Governance must separate mandatory, recommended and optional policies. Mandatory requirements can be applied globally or checked in the pipeline. Recommended are adaptable templates. Options cover specific cases. Exceptions require justification and deadline; otherwise, the platform accumulates permanent settings that no one understands.

Segregation of duties prevents a single person from changing authentication, publishing, and approving their own change in production. Git repository, pull requests, automatic validation, environments and controlled promotion transform policy into infrastructure as code. The portal or visual editor may continue to exist, but manual changes need to be reconciled with the source of truth.

radio_button_unchecked 22.16 Testing, CI/CD and troubleshooting

Policy tests must cover happy path, missing credential, invalid_token, insufficient permission, limit exceeded, unavailable backend, external timeout and malformed response. Unit or mock tests validate expressions and fragments; integration tests run the actual gateway; load testing reveals cost of parsing, remote calls, and distributed state.

The CI/CD pipeline can validate syntax, schema, references, secrets, prohibited policies, minimum order and presence of observability. Then, deploy it to a test environment, run automated cases, and promote an immutable artifact. Canary on the gateway itself reduces risk, but needs fast rollback and comparable metrics.

When troubleshooting, first identify whether the call reached the listener and which API/operation was selected. Then go through the pipeline: correlation ID, authentication, authorization, rate limit, transformation, route, backend call, outbound and on-error . Avoid starting with the backend when the gateway responded without forwarding the request.

radio_button_unchecked Case Studies

Case study 1 - Valid token, incorrect authorization: the gateway validates JWT signature and expiration, but does not verify audience. A token issued to another API is accepted. The correction is not just adding a condition; is to review the corporate fragment , add negative tests, identify affected APIs and promote new version in a controlled way.

Case study 2 - Retries storm: client, gateway and service mesh repeat the same call. During backend degradation, each original request generates multiple attempts, exhausting connections. The redesign defines a single retry owner, total budget, conditions per method and circuit breaker based on error and latency.

Case Study 3 - Forged Identity Header: The backend trusts X-User-ID, but the gateway preserves the value sent by the client when there is no token. The attacker injects the header. The fix always removes the external header, produces new value only after authentication, and restricts the backend to mTLS connections coming from the gateway.

radio_button_unchecked Chapter summary

Policies are the program run by the data plane. They observe, decide, transform, call dependencies and can close the flow. The final behavior depends on order, context , scopes, inheritance, and failure handling.

A robust pipeline authenticates and authorizes with explicit criteria, validates messages without assuming domain rules, controls traffic with correct keys, transforms only what is necessary, routes in an explainable way and applies caching and resilience according to the semantics of the operation.

Policies need to be treated like code: versioned source, review, testing, CI/CD, observability, auditing, rollback and ownership. The visual editor is just one form of authoring; does not eliminate dependencies or side effects.

Efficient troubleshooting moves through the pipeline with correlation ID and evidence per step. The central question is no longer “did the gateway fail?” and becomes “which policy made which decision, with which inputs and in how long?”.

Next step of the course

Chapter 23 will delve deeper into the architecture and operation of the Axway API Gateway, relating concepts from this chapter to Policy Studio, filters, circuits, groups, instances, caches, configuration and platform operation.

radio_button_unchecked Policy review checklist

• Each policy has a documented objective, owner, input, output and failure behavior.
• Pipeline order reflects dependencies and is covered by tests.
• Headers and identity variables cannot be forged by the consumer.
• Tokens, secrets, and personal data are removed from logs.
• External calls have timeout, authentication, metrics and fail-open / fail-closed decision.
• Limits use key, scope and counter consistent with the objective.
• Transformations preserve contract, streaming, signature and idempotence.
• Retries have a unique budget, condition and owner.
• Errors maintain correct status, secure format and correlation ID.
• Fragments are versioned, tested and have a known blast radius.
• Changes go through Git, review, validation, promotion and rollback.
• Logs, metrics, traces and auditing allow you to reconstruct decisions.

radio_button_unchecked Exercises

• Design a pipeline for JWT-protected API and explain the order of policies.
• Compare applying rate limit before and after authentication.
• Explain why a body reading policy can affect later steps.
• Propose treatment for unavailability of an external PDP .
• Describe retry risks in a POST operation.
• Set a secure cache key for authenticated multi-tenant API.
• Explain how to prevent forged identity header.
• Propose global, API and operation scopes for different policies.
• Create a test matrix for expired token, incorrect audience, and missing scope.
• Describe a troubleshooting script for error 502 produced on the gateway.

radio_button_unchecked Glossary

radio_button_unchecked Technical references

• IETF. RFC 9110 - HTTP Semantics.
• IETF. RFC 9209 - The Proxy-Status HTTP Response Header Field.
• Microsoft Learn. Policies in Azure API Management.
• Microsoft Learn. Azure API Management policy references and policy expressions.
• Microsoft Learn. Validate-content, choose, retry, cache-lookup and set-variable references.
• Axway Documentation Portal. API Gateway, Policy Studio and policy filters.
• Envoy Proxy Documentation. HTTP filters, external authorization and rate limiting.
• OWASP. API Security Top 10 - 2023 Edition.
• OpenTelemetry. Trace Context and semantic conventions for HTTP.

Update note

The syntax, availability, and scope of policies vary by product, edition, and version. Before applying examples, validate the official documentation of the deployed platform and run tests in an authorized environment.