Skip to main content

​
Request & Response Transforms

Aegis supports ordered, conditional transform rules that modify requests before they reach the upstream and responses before they are returned to the client. Transforms are configured per proxy host and executed in a user-defined sort order.
Image

​
Capabilities

CapabilityDetails
Request header manipulationSet, add, or remove request headers before proxying
Response header manipulationSet, add, or remove response headers before delivery
Path rewritingLiteral string replacement or RE2 regex with capture groups
Query parameter manipulationSet or remove URL query parameters
Host rewritingOverride the Host header sent to the upstream
Conditional redirectsShort-circuit the proxy chain with a redirect response
Conditional executionAttach WAF-style conditions to any transform rule
Variable expansionInject dynamic values (client IP, JWT claims, request ID, etc.) into header values and URLs
Ordered executionDrag-to-reorder in the UI; sort order determines execution sequence
Enable/disableToggle individual rules without deletion

​
Transform Phases

Each rule targets either the request or response phase:
PhaseWhen it runsAvailable actions
RequestBefore the request is forwarded to the upstreamHeader set/add/remove, path rewrite, host rewrite, query param set/remove, redirect
ResponseAfter the upstream response is received, before delivery to the clientHeader set/add/remove

​
Request Actions

ActionDescriptionConfig fields
set_request_headerSet a request header (overwrites existing)header_name, header_value
add_request_headerAdd a request header (appends)header_name, header_value
remove_request_headerRemove a request headerheader_name
rewrite_pathRewrite the URL path (literal or regex)path_match, path_replace, path_regex
rewrite_hostOverride the Host headerheader_value
set_query_paramSet or add a query parameterquery_param, query_value
remove_query_paramRemove a query parameterquery_param
redirectReturn a redirect response (short-circuits proxy)redirect_url, redirect_status

​
Response Actions

ActionDescriptionConfig fields
set_response_headerSet a response header (overwrites existing)header_name, header_value
add_response_headerAdd a response header (appends)header_name, header_value
remove_response_headerRemove a response headerheader_name

​
Variable Expansion

Header values and URLs support ${variable} placeholders that are substituted at runtime:
VariableDescription
${request.path}Original request path (before any rewrites)
${request.host}Incoming Host header
${request.ip}Client IP address
${request.method}HTTP method
${request.id}Aegis request ID
${upstream.host}Selected upstream hostname
${token.sub}JWT/OAuth subject claim
${token.claim.email}JWT email claim
${token.claim.username}JWT username claim
${token.claim.groups}JWT groups claim (comma-separated)
${token.claim.organizations}JWT organizations claim (comma-separated)

​
Conditional Execution

Every transform rule can optionally include one or more conditions using the same condition engine as Custom WAF Rules. Conditions use AND logic — all conditions must match for the transform to execute. This enables patterns like:
  • Set X-Forwarded-User only when a valid OAuth session is present
  • Rewrite paths only for specific User-Agent strings
  • Add CORS headers only for requests from allowed origins
  • Redirect HTTP to HTTPS only for non-API paths
Response-phase transforms can also condition on response properties:
  • Remove Server header only when the response status is 2xx
  • Add Cache-Control only when Content-Type matches a specific pattern

​
Path Rewriting

Path rewriting supports two modes:

​
Literal Replacement

Replace the first occurrence of path_match with path_replace:
ConfigValue
path_match/api/v1
path_replace/api/v2
path_regexfalse
/api/v1/users becomes /api/v2/users.

​
Regex Replacement

Enable path_regex to use RE2 regex with capture groups:
ConfigValue
path_match^/app/(.*)
path_replace/dashboard/$1
path_regextrue
/app/settings/profile becomes /dashboard/settings/profile.

​
Built-in Templates

The admin UI provides preset templates for common transform patterns:
TemplateActionDescription
Strip Server Headerremove_response_headerRemoves the Server header from upstream responses
Forward Client IPset_request_headerSets X-Forwarded-For to ${request.ip}
Rewrite Path Prefixrewrite_pathReplaces a path prefix with a new one
Add Request IDset_request_headerSets X-Request-ID to ${request.id}

​
Execution Order

Transforms execute in sort-order sequence within each phase. The UI supports drag-to-reorder, and the API accepts an ordered list of rule IDs: 
PUT /api/v1/hosts/{id}/transforms/order

{
  "ordered_ids": [3, 1, 5, 2]
}
Request transforms run before the request is forwarded. If a redirect action fires, it short-circuits the chain — no further transforms or proxying occurs.

​
API Reference

MethodEndpointDescription
GET/api/v1/hosts/{id}/transformsList all transforms for a host
POST/api/v1/hosts/{id}/transformsCreate a new transform rule
PUT/api/v1/hosts/{id}/transforms/orderReorder transform rules
GET/api/v1/transforms/{id}Get a transform rule by ID
PUT/api/v1/transforms/{id}Update a transform rule
DELETE/api/v1/transforms/{id}Delete a transform rule

​
Transform Rule Schema

FieldTypeDescription
idintegerRule ID (auto-generated)
host_idintegerAssociated proxy host
namestringDisplay name
phasestringrequest or response
actionstringTransform action (see tables above)
enabledbooleanWhether the rule is active
sort_orderintegerExecution order
configobjectAction-specific configuration
conditionsarrayOptional conditions for execution

​
Transform Config Schema

FieldTypeDescription
header_namestringTarget header name
header_valuestringHeader value (supports variable expansion)
path_matchstringPath string or regex pattern
path_replacestringReplacement string (supports $1 capture groups)
path_regexbooleanEnable RE2 regex mode for path rewriting
redirect_urlstringRedirect target URL (supports variable expansion)
redirect_statusintegerHTTP redirect status code (301, 302, 307, 308)
query_paramstringQuery parameter name
query_valuestringQuery parameter value (supports variable expansion)