> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mage.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Doppler

> Retrieve Doppler secrets in Mage configuration files without storing credentials in source code.

Only in Mage Pro.

Try our fully managed solution to access this advanced feature.

[Get started for free](https://cloud.mage.ai/sign-up?source=doppler-secrets)

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](https://docs.doppler.com/docs/enclave-projects-configs).
2. Add the secrets that Mage needs to the config.
3. Create a [service token](https://docs.doppler.com/docs/service-tokens) 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:

| Variable | Required | Description |
| - | - | - |
| `DOPPLER_TOKEN` | Yes | Service token used to read secrets. |
| `DOPPLER_PROJECT` | Yes | Default Doppler project identifier. |
| `DOPPLER_CONFIG` | Yes | Default Doppler config name, such as `dev`, `stg`, or `prd`. |
| `DOPPLER_API_HOST` | No | Doppler API host. Defaults to `https://api.doppler.com`. |
| `DOPPLER_SECRETS_CACHE_TTL_SECONDS` | No | In-memory cache lifetime in seconds. Defaults to `10`. Use `0` to fetch on every lookup. |

For example:

```bash theme={"system"}
export DOPPLER_TOKEN="dp.st.example-token"
export DOPPLER_PROJECT="analytics"
export DOPPLER_CONFIG="prd"
```

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:

```jinja theme={"system"}
{{ doppler_secret_var('POSTGRES_PASSWORD') }}
```

For example, an `io_config.yaml` profile can retrieve multiple values from the default Doppler project and config:

```yaml theme={"system"}
version: 0.1.1
default:
  POSTGRES_DBNAME: analytics
  POSTGRES_HOST: database.internal
  POSTGRES_PASSWORD: "{{ doppler_secret_var('POSTGRES_PASSWORD') }}"
  POSTGRES_USER: "{{ doppler_secret_var('POSTGRES_USER') }}"
```

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:

```jinja theme={"system"}
{{ doppler_secret_var('POSTGRES_PASSWORD', project='billing', config='prd') }}
```

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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.