Overview

Date: 2026-05-11

Time: 15:47

Overview

This is a Phase 3 example script demonstrating FTL2's secrets management system. It shows how to securely load, access, inspect, and handle sensitive values (API keys, database URLs, tokens) within automation scripts using the ftl.secrets interface. Secrets are declared upfront when creating an automation context and sourced from environment variables.

Usage Patterns

Secrets are declared as a list of environment variable names when entering the automation context:

async with automation(secrets=["API_KEY", "DB_PASSWORD"]) as ftl:
    value = ftl.secrets["API_KEY"]           # Direct access (raises KeyError if missing)
    value = ftl.secrets.get("OPTIONAL", "default")  # Access with fallback
    if "API_KEY" in ftl.secrets:             # Existence check
        # use it

Secrets can also be passed when constructing AutomationContext directly (without async with):

context = AutomationContext(secrets=["DIRECT_SECRET", "OTHER"])
context.secrets["DIRECT_SECRET"]

Typical use is passing secrets into module calls — e.g., as HTTP headers or connection strings — rather than writing them to files.

API and Configuration

• automation(secrets=["KEY1", "KEY2", ...]) — declares which environment variables to load as secrets.
• ftl.secrets["KEY"] — retrieves a secret value; raises KeyError if the env var wasn't set or wasn't in the declared list.
• ftl.secrets.get("KEY", default) — retrieves with a fallback value.
• "KEY" in ftl.secrets — checks if a secret was actually loaded (env var was set).
• ftl.secrets.keys() — lists all *requested* secret names.
• ftl.secrets.loaded_keys() — lists only the secrets that were actually found in the environment.
• len(ftl.secrets) — count of loaded secrets.
• str(ftl.secrets) / repr(ftl.secrets) — safe representation that never exposes actual values.

Environment variables must be set before running:

export API_KEY="your-api-key"
export DATABASE_URL="postgres://..."
uv run python example_phase3_secrets.py

Key Behaviors

• Secrets are never logged: str() and repr() on the secrets object redact values, preventing accidental exposure in logs or tracebacks.
• Upfront declaration required: Only secrets listed in the secrets= parameter are accessible. Accessing an undeclared key raises KeyError.
• Missing env vars don't fail at context creation: If a declared secret's env var isn't set, the context still creates successfully — the error surfaces on access (or returns a default via .get()).
• Don't write secrets to files: The examples emphasize using secrets in-memory (e.g., HTTP headers) rather than persisting them to disk.
• Conditional feature enablement: A common pattern is checking secret presence to toggle features (e.g., Slack notifications enabled only if SLACK_WEBHOOK is set).

Relationships

• Imports: ftl2.automation (async context manager), ftl2.AutomationContext (direct construction).
• Modules used within: ftl.command() for shell commands, ftl.uri() (referenced in comments) for HTTP calls with secret-bearing headers.
• Phase sequence: This is Phase 3 in the example progression, building on earlier phases that establish the automation context and module calling patterns.
• Vault integration: This example covers environment-variable-based secrets; FTL2 also supports HashiCorp Vault integration for more advanced secret sourcing (covered separately).