Reference

proxy.toml Reference

proxy.toml reference for API route configuration, header injection, dynamic routes, and request signing.

Edit this page on GitHub

proxy.toml Reference

Placed in app/proxy.toml to configure API routing for Application Modules.

[[route]]
# Static route
path = "/api/external"
target = "https://api.example.com/v1"

# Forward these headers from the browser
forward_headers = ["Accept"]

# Inject secure headers from the backend
[route.inject_headers]
"Authorization" = "Bearer ${env.API_TOKEN}"

# Optional: Filter or reshape the JSON response
[route.response_filter]
"jmespath!" = "items[*].id"
# "tera!" = '{"id": "{{ response.id }}"}'

# Graph-driven dynamic routes
[[route]]
origin_resource = "provider"
match_on = [{ property = "type", value = "internal" }]
path = "/api/{{ origin_resource.name }}/*"
target = "{{ origin_resource.api_url }}/"

Variables like ${env.X} use fast regex expansion. Variables like {{ env.X }} use full Tera templating and have access to the request context object (for HMAC signing).

Context Variables

The following context is available during Tera templating (for target, headers, filters, and responses):

  • request.method: HTTP method (e.g., GET, POST).
  • request.path: The URI path of the request.
  • request.host: The Host header or X-Forwarded-Host.
  • request.scheme: The HTTP scheme (http or https).
  • request.base_url: Combination of scheme and host.
  • request.query: Object containing all query string parameters.
  • request.query_values: Concatenated values of sorted query arguments (useful for signing).
  • request.headers: Object containing incoming request headers.
  • request.body: The raw text of the incoming HTTP body.
  • request.timestamp: Epoch time in seconds.
  • origin_resource: Properties of the currently matched graph node (if origin_resource is defined).

Dynamic Request Signatures:

For APIs that require every request to be cryptographically signed (such as Exoscale’s v2 API)

# app/proxy.toml
[[route]]
path = "/api/exoscale"
target = "https://api-ch-dk-2.exoscale.com/v2"
forward_headers = ["Accept", "User-Agent"]
[route.inject_headers]
"Content-Type" = "application/json"
"Authorization" = """
{%- set expires = request.timestamp + 600 -%}
{%- set msg = request.method ~ " " ~ request.path ~ "\n" ~ request.body ~ "\n" ~ request.query_values ~ "\n\n" ~ expires -%}
{%- set sig = msg | hmac_sha256(key=env.EXOSCALE_API_SECRET, encoding="base64") -%}
EXO2-HMAC-SHA256 credential={{ env.EXOSCALE_API_KEY }}{% if request.signed_query_args %},signed-query-args={{ request.signed_query_args }}{% endif %},expires={{ expires }},signature={{ sig -}}
"""

Action Routing

Proxy requests directly to dynamically exposed Runner services using action://<module_id>/<action_name>/<path>.

[[route]]
path = "/acme/*"
target = "action://cert-manager/start_acme_gateway/acme"

The controller will automatically locate the running service, resolve its dynamically allocated port, and tunnel the traffic.