Built-In Variables

Built-in variables in API7 Gateway are pre-defined variables that can be directly referenced in configurations. They are often used in plugin configurations, route matching, and log customization.

API7 Gateway supports three types of built-in variables:

• NGINX Variables
• APISIX Variables
• Custom Variables

These variables are evaluated in a given order.

NGINX Variables

NGINX provides variables that expose request and response information.

Commonly used variables include:

See the complete list of NGINX variables for more information.

APISIX Variables

In addition to NGINX variables, APISIX offers a variety of built-in variables:

Forwarded Header Variables

API7 Gateway rewrites the X-Forwarded-* headers before proxying a request, so a client cannot claim to have arrived over a scheme, host or port it did not use. X-Forwarded-Proto, X-Forwarded-Host and X-Forwarded-Port are replaced with values the gateway observed, Forwarded is cleared, and the connection address is appended to X-Forwarded-For.

That leaves two versions of each value, and which one a variable gives you depends on where you read it.

X-Forwarded-For Is Not Sanitized by Default

X-Forwarded-For is handled differently from the other three, and the difference matters.

Trusted Proxies

If the gateway sits behind a load balancer or CDN that sets these headers legitimately, list its addresses under apisix.trusted_addresses in config.yaml:

apisix:
  trusted_addresses:
    - 127.0.0.1
    - 172.18.0.0/16

Once it is set, behavior changes on both sides of the boundary:

• A request from a trusted address has its X-Forwarded-Proto, X-Forwarded-Host, X-Forwarded-Port and Forwarded headers put back to what that peer sent, from the $original_* copies. Its X-Forwarded-For chain is preserved, with the connection address appended. A header the peer did not send is left at the gateway's own observed value rather than being blanked.
• A request from an untrusted address has its inbound X-Forwarded-For dropped entirely, so the upstream sees only the address the gateway observed. The other three are overwritten as usual.

AI Traffic Variables

These are populated on requests proxied to an LLM provider and are nil on other traffic. They are most useful in log formats and in rate limiting keyed by token consumption.

apisix_upstream_response_time is set alongside these, in milliseconds, and is the total time the provider took rather than the time to the first token.

Billing follows llm_prompt_tokens and llm_completion_tokens separately, and cached input tokens are usually billed at a different rate from fresh ones — a cost report built on llm_total_tokens alone cannot distinguish them.

Evaluation Order

API7 Gateway evaluates variables in the given order:

1. Custom Variables
2. APISIX Variables
3. NGINX Variables

If a variable is successfully sourced in custom variables, API7 Gateway will not continue to look in APISIX variables or NGINX variables.

In other words, custom variables will overwrite variables of the same names defined in APISIX variables or NGINX variables, to better meet requirements of your specific use cases.

Variable Syntax

A valid variable name can include letters, digits, underscores (_), and periods (.).

Escaped variables with a backslash (\) are not treated as variables, for example, \$variable_name.

$var and ${var} forms

A variable can be referenced in two forms:

• $variable_name
• ${variable_name}

Both forms are supported; however, the braced form is required in certain contexts to ensure correct parsing.

The unbraced form $variable is valid when the following character cannot be part of a variable name. For example, the following forms are equivalent:

• $http_host and ${http_host}
• $arg_username-$arg_userid and ${arg_username}-${arg_userid}

When a variable is followed by a character that could belong to a variable name, the parser will incorrectly interpret it as a longer variable name. For example, with https://$http_baseurl.com, the parser would treat the entire string http_baseurl.com as the variable, which is incorrect. In this case, you should use the braced form https://${http_baseurl}.com to clearly delimit the variable.

You would also need the braced form if you use the ?? operator.

Default Values with ??

You can specify a default value for a variable using the ?? operator. If the variable is not defined, the value after the operator will be used.