Secrets & Security Basics: The Keys You Must Never Leak

Every system you'll ever touch as an FDE runs on secrets — API keys, passwords, tokens. Handle them wrong once and you'll learn why the hard way. This is the short, practical guide to never being that story.

Clarify the ask: what counts as a secret?

Before fixing anything, get precise about what you're protecting. A secret is any string that proves you are allowed to do something: read private data, write to a system, spend someone's money. If someone else learns it, they can impersonate you.

The rule of thumb: if leaking it would let a stranger act as you, it's a secret. When in doubt, treat it as a secret — over-protecting a timeout value costs nothing; under-protecting a key costs everything.

The minimum concept: secrets are config, not code

Here is the entire mental model this post hangs on:

Build it: the right way, step by step

Let's wire the CityOps 311 pull script the right way. First, the lazy way — so you can see exactly what's wrong with it:

# pull_311.py -- THE LAZY WAY (don't do this)
API_KEY = "cityops_live_9f3a2b7c4d1e"

def fetch_complaints():
    print(f"Fetching 311 complaints with key ...{API_KEY[-4:]}")

fetch_complaints()

$ python3 pull_311.py
Fetching 311 complaints with key ...4d1e

It works. That's the trap — the lazy way always works right up until it destroys you. The key is sitting in plain text, and anyone who can read the file owns it:

$ grep -rn "cityops_live" .
./pull_311.py:2:API_KEY = "cityops_live_9f3a2b7c4d1e"

Now the right way. The script reads the key from the environment — per-process variables the OS hands to your program — and refuses to run without it:

# pull_311.py -- THE RIGHT WAY
import os

api_key = os.environ.get("CITYOPS_API_KEY")
if not api_key:
    raise SystemExit(
        "CITYOPS_API_KEY is not set.\n"
        "Copy .env.example to .env, add your key, then load it:\n"
        "  set -a; source .env; set +a"
    )

print(f"Fetching 311 complaints with key ...{api_key[-4:]}")

Notice there's no try/except here — and that's deliberate. A missing secret isn't something to recover from; it's a configuration error the human must fix. Failing fast with a message that says exactly what to do is kinder than crashing ten lines later with a confusing authentication error. (That's the standing rule: only catch an exception when you can add useful context or recover from it.)

$ CITYOPS_API_KEY=demo_key_abc123 python3 pull_311.py
Fetching 311 complaints with key ...c123

$ python3 pull_311.py
CITYOPS_API_KEY is not set.
Copy .env.example to .env, add your key, then load it:
  set -a; source .env; set +a

Two files make this work in a real project. First, .env — your personal secrets, one per line, never committed:

# .env -- YOUR secrets. Never commit this file.
CITYOPS_API_KEY=cityops_live_9f3a2b7c4d1e

Second, .gitignore — the bouncer that keeps .env out of Git. (Gitignore patterns were covered in The Terminal and Git, Demystified — this is where that lesson pays for itself.)

# .gitignore
.env
__pycache__/
*.pyc

$ git status --short
?? .gitignore

See that? Git sees .gitignore but not .env. Your secrets are invisible to version control. And third, .env.example — a committed template with fake values showing teammates what they need:

# .env.example -- commit this. It shows WHAT is needed, not the values.
CITYOPS_API_KEY=your_key_here

Break it: why "just delete it" doesn't work

Suppose the lazy way already happened — the key got committed. You delete the line and commit the fix. Safe now? Let's check:

$ git log --all -p -- config.py | grep -c "cityops_live_9f3a2b7c4d1e"
2

The key appears twice in history even though the current file is clean. Git never forgets — every clone, every fork, every backup of that repo still contains the key. A committed secret is a leaked secret, permanently. There is no "oops" button; there is only the revoke playbook:

Productionize: least privilege and secret managers

The .env pattern covers you on your own machine. Two more ideas carry you into real client work.

Least privilege: keys should be weak on purpose

Least privilege means every secret gets the minimum power it needs — nothing more. When the city issues your 311 key, ask for read-only access to the complaints dataset, not admin access to the whole portal. Then, when (not if) a key leaks, the blast radius is a bruise instead of a crater. A read-only key that leaks is an incident; an admin key that leaks is a disaster.

Secret managers: the team-scale answer

.env files don't scale to teams — you can't Slack secrets around (that's just leaking with extra steps). For shared and production systems, teams use a secret manager: a locked vault (like HashiCorp Vault, AWS Secrets Manager, or Doppler) where secrets live encrypted, access is logged, and rotation is a button press instead of a scavenger hunt. You don't need to operate one today — just know the shape of the answer: local dev → .env; teams and production → a secret manager.

Communicate: telling the customer a key leaked

This is the part nobody teaches and everybody needs. If a secret leaks on your watch, the customer hears it from you — fast, specific, and without minimization:

Note the shape: what happened, what you already did, what the impact was, what changes next. No excuses, no jargon, no "it was just a dev key." Customers forgive mistakes; they don't forgive cover-ups.

CityOps: wire it into the project

Back to the milestone. Your CityOps scaffold from Milestone 1: The CityOps Scaffold now gets its secrets discipline:

cityops/
├── .env              # real key -- gitignored, on your machine only
├── .env.example      # CITYOPS_API_KEY=your_key_here -- committed
├── .gitignore        # contains: .env
└── scripts/
    └── pull_311.py   # reads os.environ, fails fast if unset

Every future CityOps script that needs a credential follows the same three-file pattern. When a teammate joins, they copy .env.example to .env, paste their own key, and everything works — no secrets in chat, no secrets in Git, no Monday-morning Slack messages from strangers.