Skip to main content
Mage can retrieve secrets from a Doppler project and config when it renders YAML and SQL templates. Use this integration for values such as database passwords, API keys, and access tokens that should not be committed to your Mage project. In Mage Pro, this guide is also available from Settings > Access & security > Secrets management.

​
Prerequisites

Before configuring Mage:
  1. Create a Doppler project and config.
  2. Add the secrets that Mage needs to the config.
  3. Create a service token with access to that config. Prefer a dedicated, read-only token for each Mage environment.

​
Configure Mage

Set these environment variables on every Mage process that renders configuration containing Doppler references: For example:
Restart Mage after changing its environment variables. Do not put DOPPLER_TOKEN in io_config.yaml, pipeline code, or version control.

​
Reference a secret

Use doppler_secret_var anywhere Mage template variables are supported:
For example, an io_config.yaml profile can retrieve multiple values from the default Doppler project and config:
Mage requests the computed value for the named secret. If the secret does not exist in the selected project and config, template rendering fails instead of returning an empty value.

​
Override the project or config

The environment variables define the defaults. Pass project or config for a reference that should use a different Doppler scope:
You can override either value independently. The runtime still uses DOPPLER_TOKEN, so that token must be authorized to read every referenced project and config.

​
Cache behavior and secret rotation

Mage caches the complete secret set for each API host, project, and config in process memory. The default cache lifetime is 10 seconds. References to the same scope reuse that cached result until its TTL expires. Set DOPPLER_SECRETS_CACHE_TTL_SECONDS=0 to disable caching. This makes secret changes available on the next template render, but increases Doppler API traffic and makes rendering more sensitive to temporary network failures. A negative TTL is treated as 0. After the TTL expires, Mage fetches the config again on the next lookup. Existing database connections and clients may continue using an older credential until they are recreated.

​
Troubleshooting

​
Missing Doppler configuration

If Mage reports missing DOPPLER_TOKEN, DOPPLER_PROJECT, or DOPPLER_CONFIG, confirm the variables are present in the environment of the Mage process, then restart it. Setting them only in an interactive shell does not update an already-running deployment.

​
Secret not found

Confirm that the secret name is exact and case-sensitive, the selected project and config contain it, and the service token can read that scope. Check per-reference project and config overrides as well as the defaults.

​
Doppler API request fails

Verify that Mage can reach https://api.doppler.com, the service token is valid, and the project and config identifiers are correct. If your environment uses a proxy or a custom Doppler API endpoint, set DOPPLER_API_HOST to the reachable base URL without a trailing path.

​
A rotated value is not used immediately

Wait for DOPPLER_SECRETS_CACHE_TTL_SECONDS to elapse and trigger another template render. Recreate any open database connection or client that was initialized with the previous value. For rotation-sensitive workloads, temporarily reduce the TTL or set it to 0, considering the additional API traffic.

​
Security recommendations

  • Use a separate Doppler service token for each Mage environment.
  • Grant the token access only to the projects and configs that environment requires.
  • Store the token in your deployment platform’s protected environment configuration, not in Mage project files.
  • Rotate tokens and application credentials regularly, and revoke unused tokens.
  • Avoid logging rendered configuration or secret values.