Skip to main content
The dlt.secrets accessor provides secure, dictionary-like access to sensitive configuration values like API keys, passwords, and tokens. It only queries providers that support secrets storage.

​
Basic Usage

import dlt

# Access secret values
api_key = dlt.secrets["api_key"]
password = dlt.secrets.get("database.password")

# Check if secret exists
if "optional_token" in dlt.secrets:
    token = dlt.secrets["optional_token"]

# Set secrets programmatically
dlt.secrets["custom.api_key"] = "sk-..."

​
Methods

​
__getitem__(field: str)

Get a secret value by field name. Raises ConfigFieldMissingException if not found.
​
field
str
required
Secret key to retrieve. Use dot notation for nested values (e.g., "destination.postgres.password").
Returns: The secret value. Example: 
api_key = dlt.secrets["sources.github.api_key"]

​
get(field: str, expected_type: Type = None)

Get a secret value with optional type casting. Returns None if not found.
​
field
str
required
Secret key to retrieve.
​
expected_type
Type
default:"None"
Expected type to deserialize the value into.
Returns: The secret value cast to expected_type, or None if not found. Example: 
api_key = dlt.secrets.get("api_key", str)
connection_string = dlt.secrets.get("destination.postgres.credentials")

​
__setitem__(field: str, value: Any)

Set a secret value programmatically.
​
field
str
required
Secret key to set. Use dot notation for sections.
​
value
Any
required
Secret value to store.
Example: 
dlt.secrets["destination.bigquery.credentials"] = {"project_id": "my-project", ...}

​
__contains__(field: str)

Check if a secret exists. Example: 
if "api_token" in dlt.secrets:
    authenticated_request(dlt.secrets["api_token"])

​
Automatic Injection with dlt.secrets.value

Use dlt.secrets.value as a default argument value to automatically inject secrets: 
import dlt
from dlt.sources.helpers import requests

@dlt.resource
def github_repos(api_key=dlt.secrets.value):
    """dlt will automatically inject api_key from secrets"""
    headers = {"Authorization": f"Bearer {api_key}"}
    response = requests.get("https://api.github.com/user/repos", headers=headers)
    yield response.json()

​
Type Annotations for Secrets

Use type annotations to indicate secret parameters: 
from dlt.common.typing import TSecretValue

@dlt.source
def my_source(api_key: TSecretValue, api_url: str = dlt.config.value):
    """api_key is treated as secret, api_url as regular config"""
    ...

​
Secret Storage Providers

The dlt.secrets accessor reads from secure providers only:
  1. Environment variables (e.g., SOURCES__GITHUB__API_KEY)
  2. secrets.toml file in .dlt/ directory
  3. Airflow Variables/Connections (when running in Airflow)
  4. Google Secret Manager
  5. AWS Secrets Manager
  6. Azure Key Vault
  7. Other configured secret backends
Important: Secrets are NOT read from config.toml as it’s not considered secure.

​
Secrets File Example

In .dlt/secrets.toml: 
[sources.github]
api_key = "ghp_..."

[destination.postgres.credentials]
database = "mydb"
username = "user"
password = "secret_password"
host = "localhost"
port = 5432
Security Note: Add .dlt/secrets.toml to .gitignore to prevent committing secrets to version control.

​
Environment Variables

Secrets can be provided via environment variables: 
export SOURCES__GITHUB__API_KEY="ghp_..."
export DESTINATION__POSTGRES__CREDENTIALS__PASSWORD="secret_password"

​
Credentials Configuration Classes

For structured credentials, use CredentialsConfiguration subclasses: 
from dlt.common.configuration.specs import ConnectionStringCredentials

@dlt.source
def my_source(credentials: ConnectionStringCredentials = dlt.secrets.value):
    # credentials will be automatically parsed from connection string
    # or from individual fields
    engine = create_engine(credentials.to_native_representation())
    ...

​
Secret Validation

dlt ensures secrets are only retrieved from secure providers. If a value marked as secret is found in a non-secure provider (like config.toml), a ValueNotSecretException is raised. 
# This will fail if api_key is found in config.toml instead of secrets.toml
api_key: TSecretValue = dlt.secrets["api_key"]

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us