Header policy execution and behavior
The header policy modifies HTTP headers as requests and responses pass through ION API Gateway. Policy placement determines whether the header policy affects the request before it reaches the backend or the response before it is returned to the client. Execution order, attachment scope, and context variable availability directly affect header policy behavior.
Policy execution order
Request flow execution
In the request flow, suite-level policies execute before endpoint-level policies. All request flow policies execute before ION API Gateway sends the request to the target backend.
Within the same scope, policies execute in the order in which they are configured. A later policy can override changes made by an earlier policy.
Response flow execution
In the response flow, endpoint-level policies execute before suite-level policies. Response flow policies execute after the backend responds and before the client receives the response.
This execution order is important when sanitizing backend headers or enforcing standardized response headers.
Execution sequence example
A typical execution sequence is:
1. Suite request policies
2. Endpoint request policies
3. Request sent to backend
4. Endpoint response policies
5. Suite response policies
6. Response sent to client
Header behavior
Setting headers
When you set a header that does not exist, the header policy creates a new header.
When you set a header that already exists, the header policy updates the existing value. The header policy does not create duplicate headers.
Deleting headers
When you delete a specific header, the header policy removes that header from the current flow.
When you specify * as the header name, the header policy deletes all headers in the current flow.
Case sensitivity
Header names are case-insensitive according to HTTP standards. Header values are case-sensitive.
Context object behavior
Context object creation
The context object is created when ION API Gateway receives a request. Context variables are populated based on authentication, URL parsing, and configuration data.
Variable availability
Not all context variables are available in every authentication scenario.
User-related variables require user-based authentication and are not available for anonymous requests or client credential grant flows.
URL-based variables depend on the structure of the request URL.
Service account variables are available only when service account authentication is used.
Read-only behavior
Context variables are read-only. Header policies can reference context variables but cannot modify them.
Best practices
Security considerations
Use response flow policies to remove internal or sensitive headers before returning responses to clients.
Review header exposure when referencing tenant identifiers or user identity values.
Execution planning
Plan policy attachment scope carefully. Suite-level policies affect all endpoints in the suite, while endpoint-level policies affect only a specific endpoint.
Review execution order when multiple policies modify the same header to prevent unintended overrides.
Multi-tenant environments
Use context variables instead of hardcoded values for tenant-specific headers to maintain tenant isolation and reduce configuration errors.