Managing secrets and API keys

A secret is any value that gives access: API keys, database passwords, JWT signing keys, cloud access keys, webhook secrets, private keys and tokens. Leaked secrets are one of the most common ways real incidents start, and the cause is usually mundane: someone committed a .env file to a public GitHub repository.

In this tutorial you will keep secrets out of code, load them safely in Python and in a Vite frontend, stop them reaching Git, scan for leaks, and learn what to do in the first hour after one leaks.

Prerequisites: Python 3.10 or newer, Git installed, a terminal and a small project folder (the Brew & Bean API works). All keys in this lesson are fake; use fake values while you practise.

Not a secret: your public site URL, the public part of a key pair, a Firebase web config meant for browsers (though protect it with security rules), a publishable key that the provider designs for use in browsers. If the provider's docs say "publishable" or "public", it is meant to be seen. If they say "secret", it must never appear in client code.

Secrets do not belong in source code. Not in .py or .js files, not in comments, not in Git history, not in Docker images, not in screenshots or chat messages. Code is copied to many places (laptops, GitHub, CI, teammates). A secret that is only in the environment of the running server is in far fewer places.

The common pattern is the twelve-factor approach: keep configuration in environment variables, and give each environment (your laptop, test, production) its own values.

DATABASE_URL=sqlite:///brewbean.db
SMS_API_KEY=dev-key-not-real

Plain NAME=value lines, no quotes or spaces needed. This file stays on your machine and is never committed.

# config.py
import os
from dotenv import load_dotenv

load_dotenv()  # reads a local .env file if present; real environment variables win


def require(name: str) -> str:
    value = os.environ.get(name)
    if not value:
        raise RuntimeError(f"Missing required setting: {name}")
    return value


DATABASE_URL = require("DATABASE_URL")
SMS_API_KEY = require("SMS_API_KEY")
DEBUG = os.environ.get("DEBUG", "false").lower() == "true"

require makes the app fail fast with a clear message when a setting is missing, instead of failing later in a confusing way. DEBUG defaults to false, so the safe option is what happens when nobody sets anything.

# show_config.py
import config

print("Database:", config.DATABASE_URL)
print("SMS key loaded:", bool(config.SMS_API_KEY))
print("Debug:", config.DEBUG)

Notice it prints whether the key is loaded, not the key itself. Never print secrets in logs.

Try renaming .env and running again: you should get RuntimeError: Missing required setting: DATABASE_URL. In production you do not ship a .env file at all. You set the same variable names in your host's settings panel (Render, Railway, Vercel, Azure, AWS and others all have an environment variables or secrets section) or in your orchestrator's secret store.

DATABASE_URL=
SMS_API_KEY=
DEBUG=false

Safe to commit: names only, no real values.

Tell Git to ignore the real file before your first commit. Once a secret is committed, it lives in history even if you delete the file in a later commit.

.env
.env.*
!.env.example
*.pem
*.key
secrets/

.env.* ignores variants like .env.production, and !.env.example makes an exception so the template is committed. Also ignore private key files.

Anything bundled into a React or Vite frontend is delivered to every visitor's browser. Anyone can open developer tools and read it. In Vite, only variables starting with VITE_ are exposed to your frontend code, which is a clear signal: never put a secret in a `VITE_` variable. The same is true for NEXT_PUBLIC_ in Next.js and REACT_APP_ in Create React App.

The fix is a backend proxy: the frontend calls your own API (POST /orders), and your server calls the third-party service using its secret. Your server can also enforce who may call it and how often. This is especially important for paid AI APIs: a key in the browser lets strangers spend your money.

Humans forget, so automate. Secret scanners look through files and Git history for things that look like keys. Gitleaks and TruffleHog are free open-source scanners. GitHub also offers secret scanning and push protection, which blocks pushes containing known key formats (availability depends on the repository type and plan; check GitHub's documentation).

# Scan the repository, including its history (after installing gitleaks)
gitleaks detect --source . --verbose

# Newer gitleaks versions also accept:
gitleaks git --verbose

If a secret is found you get the file, line, commit and rule name. Install options are in the gitleaks README (Homebrew, Docker, or a release binary for Windows). Command names changed between versions, so run gitleaks --help to see which your version has.

Better still, stop secrets before they are committed with a pre-commit hook. The pre-commit tool runs checks on every git commit.

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/gitleaks/gitleaks
    rev: <latest release tag, for example v8.xx.x>
    hooks:
      - id: gitleaks

Replace rev with a real release tag from the gitleaks releases page. Then run pip install pre-commit and pre-commit install. From then on, a commit that contains something that looks like a key is blocked.

Good habits that apply everywhere: give each secret least privilege (a read-only database user for reports, an API key limited to one action or one IP range), use different secrets per environment (a leaked development key must not open production), rotate regularly and after staff leave, and set spending alerts or budgets on pay-per-use services so abuse is noticed early.

Do not paste real keys, passwords or customer data into AI chat tools or prompts, and be careful when AI coding assistants read your project folder: configure them to ignore .env. AI-generated code often hard-codes example keys; replace them with environment variables before committing. See *Security pitfalls in AI-written code* in Build with AI.

You are a security-minded code reviewer. Review the code below and find every hard-coded secret or configuration value that should be an environment variable (API keys, passwords, tokens, connection strings, signing keys). For each one, give the line, suggest an environment variable name, and rewrite the code to read it with a clear error if it is missing. Also give me a `.env.example` and the `.gitignore` lines I need. Do not invent real-looking secrets.

Language: [e.g. Python / Node]

Code (replace any real secrets with FAKE before pasting):
[paste code]

What to expect: Check that the rewritten code has no default values that are real secrets and that nothing secret is printed or logged. Always replace real keys with fake ones before sharing code with any AI tool.

Typical questions: "Where do you store API keys?" (environment variables or a secret manager, never in code or Git). "What do you do if a key is committed by mistake?" (rotate first, then clean up and add prevention). "Can a React app hide an API key?" (no; use a backend proxy). "What is secret rotation?" A strong answer also mentions least privilege, separate environments and scanning.