> For the complete documentation index, see [llms.txt](https://docs.serverlessapigateway.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.serverlessapigateway.com/reference/mapping-overview/env-and-secret-replacement.md).

# Environment Variables and Secret Replacement

Replace `$env.*` and `$secrets.*` placeholders at load time so sensitive values stay outside repo config. The gateway resolves these placeholders when it parses the config at startup, replacing them with values from Cloudflare environment variables and secrets. This keeps credentials out of your JSON config files and version control.

**Last reviewed:** 2026-03-06

## When to use this

Use the mapping and variables reference when you need to transform, inject, or replace values in upstream requests. Mapping lets you forward selected headers, query parameters, JWT claims, and config variables to the upstream without modifying your backend code.

## Key concepts

* The `mapping` block on a path entry defines which headers and query parameters to send to the upstream. Only mapped values are forwarded -- unmapped client headers and query params are dropped.
* Mapping sources include `$request.headers.*`, `$request.query.*`, `$request.jwt.*` (any JWT claim), `$config.*` (global variables), and `$route.*` (route-level variables).
* Global `variables` are defined at the top level of the config and available to all routes. Route-level `variables` are defined inside a path entry and override global variables with the same name.
* `$env.*` and `$secrets.*` placeholders are replaced at config load time, not at request time. This means environment variables and secrets are baked into the parsed config once at startup.
* If a mapping source resolves to `null` or `undefined`, the gateway sends an empty string for that header or query parameter. Use the debugging guide to trace missing values.

## Repo-grounded example

```json
{
  "authorizer": {
    "type": "auth0",
    "domain": "$env.AUTH0_DOMAIN",
    "client_id": "$env.AUTH0_CLIENT_ID",
    "client_secret": "$secrets.AUTH0_CLIENT_SECRET",
    "redirect_uri": "https://api.example.com/api/v1/auth0/callback",
    "callback_uri": "https://app.example.com/auth/callback",
    "jwks_uri": "https://tenant.us.auth0.com/.well-known/jwks.json",
    "scope": "openid profile email"
  },
  "paths": [
    {
      "method": "GET",
      "path": "/api/v1/auth0/callback",
      "integration": { "type": "auth0_callback" }
    }
  ]
}
```

This snippet uses `$env.AUTH0_DOMAIN`, `$env.AUTH0_CLIENT_ID`, and `$secrets.AUTH0_CLIENT_SECRET` placeholders. At startup, the gateway replaces these with the corresponding Cloudflare environment variables and secrets, so the parsed config contains the actual values.

## Troubleshooting

* If a mapped header arrives empty at the upstream, verify the source exists: check that the JWT claim is present in the token, the request header was sent by the client, or the variable is defined in config.
* If `$request.jwt.sub` is null on a route without `auth: true`, remember that JWT claims are only available after successful token validation -- add `auth: true` to the route.
* If route variables are not overriding global variables, confirm the variable name matches exactly (case-sensitive) and that the route-level `variables` block is inside the path entry, not at the top level.
* Use a tool like jwt.io to decode your test token and confirm the claim names match what your mapping expects (e.g., `sub` vs `user_id`).

## Related docs

* [README](/configuration/variable-mapping.md)
* [priority variables](/configuration/priority-variables.md)
* [gateway troubleshooting matrix](/troubleshooting/wrangler-deploy-guide/gateway-troubleshooting-matrix.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.serverlessapigateway.com/reference/mapping-overview/env-and-secret-replacement.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.