Storage guide

How to store API keys securely: environment variables and beyond

Most API key leaks don't start with a sophisticated attack — they start with a developer following a quick-start tutorial that said "paste your key here." This guide covers the right pattern for every stage of a project: local development, preview deploys, production, and when a team grows large enough to need a real secrets manager.

• Why keys end up in code
• The .env file pattern
• Build-time vs. runtime injection
• Platform-native secrets
• When to use a secrets manager
• Mistakes to avoid
• FAQ

Why API keys end up in source code

The quick-start documentation for almost every API includes a code example with the key pasted directly into the snippet. The developer copies it, the code works, they commit it without thinking, and push. A few seconds later an automated bot that watches the GitHub public events API has harvested the key. This is not a theoretical scenario — it happens thousands of times per day across public repositories.

The root causes are always the same: the documentation normalized inline keys, the developer did not have a clear mental model for "where secrets go instead," and there was no automated check to catch the commit before it reached the remote. This guide fixes the middle problem — the mental model. The pre-commit hook and CI scan fix the third.

The .env file pattern

The foundation of API key management for local development is the .env file. A .env file is a plain text file that sits at the root of your project, contains your secrets as KEY=value pairs, and is never committed to version control. Your application reads the values from the file at startup, so the key is available to the code without ever appearing in a committed file.

Setting it up (Node.js / dotenv)

# Install the dotenv package
npm install dotenv

# .env — local secrets (NEVER commit this file)
OPENAI_API_KEY=sk-proj-abc123...
STRIPE_SECRET_KEY=sk_live_xyz789...
DATABASE_URL=postgresql://user:pass@localhost/myapp

// Load .env before any other imports that use process.env
import "dotenv/config";

// Now process.env.OPENAI_API_KEY is available
const response = await openai.chat.completions.create({
  model: "gpt-4o",
  messages: [{ role: "user", content: prompt }],
});
// openai SDK reads process.env.OPENAI_API_KEY automatically

Setting it up (Python / python-dotenv)

# Install
pip install python-dotenv

# In your code
from dotenv import load_dotenv
import os

load_dotenv()  # reads .env from the project root
api_key = os.getenv("OPENAI_API_KEY")

The three files you need

# .gitignore — add these lines
.env
.env.local
.env.*.local

Build-time vs. runtime environment variables

This is the distinction that causes the most confusion with modern frontend frameworks, and it has real security consequences.

A runtime environment variable is read by your server process when it starts. The value is never baked into any file that leaves your server. It is appropriate for any secret — database passwords, secret API keys, webhook signing secrets.

A build-time environment variable is injected into your JavaScript bundle during the build step and shipped to every browser that loads your application. Next.js does this with any variable prefixed NEXT_PUBLIC_. Vite does it with VITE_ prefixed variables. The resulting value appears as a string literal in dist/assets/index-abc123.js — anyone who opens DevTools can read it.

If your frontend needs to call an API that requires a secret key, the answer is always to put a server-side proxy in between: the browser calls /api/your-endpoint on your server, your server holds the key as a runtime env var, calls the third-party API, and returns the result. This is the pattern used by Next.js Route Handlers, Nuxt server routes, and any Express/Fastify backend. If you have no server, use a serverless function (Vercel Functions, Netlify Functions, Cloudflare Workers) as the proxy layer.

Platform-native secrets: no file required

When you deploy to a managed platform, you do not need a .env file on the server. Every major platform provides a UI for setting environment variables that are injected at runtime without touching the filesystem. This is strictly better than a file on disk: the values are encrypted at rest, scoped to your project, and not present in any artifact you deploy.

When to use a secrets manager

Platform-native env vars are the right choice for most applications. A dedicated secrets manager becomes necessary when you hit specific requirements that env vars cannot satisfy.

For most early-stage projects: use platform-native env vars. When you have multiple services consuming the same secret, or your security policy requires rotation and audit logs, evaluate AWS Secrets Manager, HashiCorp Vault, or Doppler (the most developer-friendly onramp for small teams).

Mistakes to avoid

• ✗

  Hardcoding keys directly in source files

  The most common mistake. Even in a private repository, any collaborator, GitHub Actions runner, or third-party integration that reads the repo has access to the key. Private repos become public, and repo access gets granted more broadly than intended.

• ✗

  Committing a .env file

  Often happens after adding .env to .gitignore but not removing the file from the tracked index first. Check with git ls-files --cached .env. If it appears, git rm --cached .env removes it from tracking without deleting the file.

• ✗

  Passing server-side secrets as NEXT_PUBLIC_ / VITE_ variables

  These prefixes tell the build tool to inline the value into the client bundle. An OpenAI key passed as NEXT_PUBLIC_OPENAI_API_KEY is shipped to every browser and readable in DevTools. Use a server-side Route Handler or API route instead.

• ✗

  Logging environment variables

  console.log(process.env) or print(os.environ) in a file that gets committed dumps every environment variable — including secrets — into your logs and potentially into the repository if you commit log output. Treat all env var values as opaque and never log the full environment object.

• ✗

  Bundling .env into a Docker image or deployment artifact

  A COPY . . in a Dockerfile copies everything in the build context, including any .env file that is present. Add .env to your .dockerignore file (not just .gitignore) and use Docker build arguments or runtime --env-file instead.

• ✗

  Sharing secrets over Slack, email, or GitHub issues

  Chat messages and issue comments are stored indefinitely, often indexed by third-party apps, and frequently exported in data-retention archives. Rotate any key that was shared this way and share replacements through a password manager (Bitwarden, 1Password) instead.

• ✗

  Using the same API key across all environments

  A single key that serves development, staging, and production means a leak in any environment compromises all three. Most API providers make it easy to generate additional keys in their dashboard. The cost of managing separate keys is far lower than the cost of a production incident from a leaked dev key.

Check your current files for leaks

If you are reading this guide because you suspect a key may already be in your codebase or git history, paste a file or snippet into LeakCheck for a fast browser-based scan — no upload, no signup.

Scan your code in LeakCheck →

For a full audit of git history (including deleted files and past commits), see the companion detection guide:

Scan a git repository for secrets (gitleaks, GitHub Actions) →

I already committed a key — what do I do? →

Frequently asked questions

Also in the Copper Bay Labs ship-safety suite

Correct key storage is one layer. These free tools cover the rest of the pre- and post-deploy security stack: