Where to Put API Keys: .env Files Explained

Claude Code has asked you to "add your API key", and you have a long string of letters and numbers ready to paste. Before it goes anywhere, it helps to know where to put API keys so they stay private.

This guide covers where a key should live while you build, where it goes when your site is live, how Claude Code sets it all up from a plain-English message, and what to do if a key ever ends up somewhere it shouldn't.

An API key is a secret password that lets your project use an outside service, such as an email service. If that's new territory, what an API key is and why services use them covers the basics first.

Why shouldn't API keys sit in your code?

Because code gets shared, and anyone who sees your key can use your account. If someone finds an email service key, they can send email from your domain and run up your bill.

Your code travels further than you might expect. Most projects built with Claude Code are saved to Git, a tool that keeps a history of every change, and uploaded to GitHub, a website that stores that history online. Once a key is in that history, it stays in older versions even after you delete it from the current file.

Keeping keys out of your code means:

• you can share or publish your code without sharing your secrets
• you can change a key without changing any code
• your live site and your own computer can use different keys

What is a .env file?

A .env file (said "dot env") is a small, private text file in your project that holds settings your code needs but shouldn't contain, such as API keys. Each line is a name and a value.

Here's what one holds, shown as a table:

Your code refers only to the name, EMAIL_API_KEY, and reads the value from the .env file when it runs. These named settings are called environment variables.

The file stays private because of a second file called .gitignore. It's a list of files Git should never save or upload. As long as .env is on that list, your keys stay on your computer. Many project templates add it for you; Next.js, for example, adds .env files to .gitignore by default.

One catch: .gitignore only protects files Git isn't already tracking. If .env was saved to Git before it was added to the list, Git keeps tracking it until it's removed from Git's history of tracked files.

How do you set up a .env file with Claude Code?

You describe what you want, and Claude Code creates the file, updates .gitignore and changes the code to read from it. Start with a quick tidy-up of anything already in your project:

I'd like all secret keys kept out of my code. Please check the whole project for any keys typed straight into files, move them into a .env file, and make sure .env is listed in .gitignore. Then tell me in plain words what you changed and whether a key was ever saved to Git.

Claude Code will list what it found, what it moved and whether your .gitignore needed fixing. If it tells you a key was already saved to Git, treat that key as exposed and follow the leak steps further down.

When you have a new key to add, ask for the spot to be ready first:

I have a new API key for my email service. Add a line for it in the .env file with a clear name, leave the value empty, and tell me how to open that file so I can paste the key in myself.

You'll get the name it chose and directions to the file. Paste the key, save, and ask Claude Code to check the project can read it.

Where do API keys go on your hosting platform, like Vercel?

Your .env file never leaves your computer, so your live site needs its own copy of each key. Hosting platforms keep these in their settings as environment variables, encrypted and out of your code.

On Vercel, the steps are:

1. Open your project, then select Environment Variables in the sidebar (under Settings).
2. Type the Name exactly as it appears in your .env file.
3. Paste the key as the Value.
4. Choose where it applies: Production (your live site), Preview (test versions) or Development (your computer).
5. For secret keys in Production or Preview, switch Sensitive on. Vercel then stores the value so it can't be read back.
6. Click Save, then redeploy your project. Vercel applies changes only to new deployments, so the live site keeps the old setting until you do.

Not sure which names your live site needs? Ask:

My site is hosted on Vercel. List every environment variable the live site needs, with the exact name of each and whether it belongs in Production, Preview or Development. Don't show me any key values.

If you've connected Vercel to Claude Code as a connector, Claude Code can add the variables there itself. A connector (an MCP server) lets Claude Code use another service on your behalf, and Vercel's includes tools for creating and editing environment variables. Adding a connector to Claude Code takes a couple of minutes in Customize, then Connectors.

What should you do if an API key leaks?

Replace the key straight away. GitHub's own advice is that revoking or replacing a leaked secret comes first, because once the old key stops working, the copy that leaked is useless. Deleting it from your code isn't enough on its own.

Do it in this order so your live site keeps working:

1. Make a new key in the service's dashboard. Leave the old one on for now.
2. Swap it in everywhere: your .env file and your hosting platform's environment variables.
3. Redeploy and test that the live site works with the new key.
4. Turn off the old key in the service's dashboard.

This is the order Vercel recommends, since turning the old key off first breaks every deployment still using it.

I think my email API key has leaked. Walk me through replacing it in the right order, update the key wherever this project uses it, and check whether any other secrets are exposed.

GitHub also blocks some keys from being uploaded to public projects by default, through a feature called push protection. It catches many common key formats, but it's a safety net, not a replacement for keeping keys in .env.

How does this work with SimpleSends?

SimpleSends is a transactional email service built for people who build with Claude Code but don't write code. Your live project still uses a secret key to send email, and every point in this guide still applies to it.

The difference is in who handles it. Claude Code creates the SimpleSends key through the connector and adds it to your project, so you never copy or paste it.

To connect:

1. Sign up on the SimpleSends website and follow the steps there to set up the email address you'll send from. To send from your own domain, this includes adding a few DNS records where your domain is registered.
2. In Claude Code, open Customize, then Connectors, choose Add, then Add custom connector. Use the name SimpleSends and the MCP server URL https://mcp.simplesends.com/mcp
3. When Claude prompts you to connect, log in to SimpleSends.
4. Back in the Claude Code chat, tell Claude Code:

I've connected SimpleSends for all transactional email.

It takes it from there, including adding what your project needs to send email. Once it's set up, send a test email from the chat to check the key works, or read the full guide to sending emails from Claude Code.