Get the free coreGet core

Where to store API keys on a Mac: .env, Keychain or a secrets manager

Updated 6 min readSection 05 / Threats
SHORT ANSWER

Keep keys out of code and hand them to your app through an environment variable or a secrets manager. On a Mac you have three practical homes: a .env file that Git ignores, an item in the macOS Keychain that you read with the security command, or a secrets manager CLI such as 1Password's. Each one fails in a different way, and none stops a program that runs as you.

This page covers where to store API keys on a Mac: the three places developers really use, the commands, and where each one breaks. If you are not sure what a key is yet, start with what an API key is.

01Where to store API keys: the three options side by side

PlaceWhat it gives youWhere it fails
.env fileSimple, and env vars are unlikely to be checked into the repo by accidentPlain text on disk. Malicious packages search for .env files
macOS KeychainBuilt in. With -w last, the command prompts for the secret, which is the recommended wayAMOS, a Mac password-stealing program, harvested Keychains
Secrets manager CLISecrets load without plaintext .env filesThe key still ends up in the environment of your app, see below

Pick one and use it everywhere. A mix is how a key ends up in a forgotten file. Your situation decides where to store API keys:

Your situationA sensible default
One developer, one Mac, a few keysA .env file in .gitignore, plus a spend limit at the provider
You want no key in any file on diskA Keychain item read with the security command
A team, many keys, keys that change oftenA secrets manager CLI, with keys that expire

02Option 1: a .env file, kept out of Git

A .env file is a plain text file of settings, one per line. A library such as dotenv loads those lines into process.env. Create the file in the root of your project, and keep one file per environment.

The rule that matters: do not commit the .env file, unless you encrypt it with dotenvx. A simple test is whether the codebase could be made open source at any moment without compromising any credentials.

Add the file to .gitignore. GitHub's Node template does it like this and keeps a safe example file:

.env
.env.*
!.env.example

A ! at the start of a line negates the pattern. One trap: files already tracked by Git are not affected by .gitignore. If you committed .env earlier, stop tracking it:

git rm --cached .env

That only stops future tracking. If the key was ever pushed, treat it as exposed and follow API key exposed on GitHub.

03Option 2: the macOS Keychain and the security command

The Keychain is the Mac's built-in store for passwords. The security command talks to it from Terminal. add-generic-password stores an item and needs an account name and a service name. Put -w at the end and the command prompts you for the password, which is the recommended way.

This is an example built from those documented options, not a command copied from the manual. Replace SERVICE with your own name; $USER fills in your Mac account name:

security add-generic-password -a "$USER" -s SERVICE -w

Do not add -A: it lets any application read the item without warning, and the manual marks it insecure. To read the secret back, -w on find-generic-password prints only the password. This line, also an example, puts it into an environment variable for the current Terminal session:

export MY_API_KEY="$(security find-generic-password -s SERVICE -w)"

Put that in a script or a shell function that starts your app, so the key never sits in a project file.

The Keychain is not a vault against malware. AMOS, a Mac stealer that copies passwords and files, harvested Keychains, browser credentials and sessions. One AMOS variant ignores .env files but still takes keychains and documents. Defenders are advised to alert on unusual reads of the Keychain and of cloud and developer files.

04Option 3: a secrets manager CLI

A secrets manager keeps keys in an encrypted store outside your project and hands them to a program when it starts. The 1Password CLI does this with op run, which loads secrets into environment variables so apps and scripts get their values without plaintext .env files. The secrets are made available as environment variables only for the duration of the process.

For developer machines the advice is to use short-lived credentials, store secrets in vaults, and avoid long-lived tokens in environment files or local configuration. The short-lived part matters most. A key that expires is a smaller prize.

05Environment variables: what they do and what they do not

All three options end the same way: the key reaches your app as an environment variable, which is a named value the system hands to a program when it starts. That beats hard-coding, and there is little chance of an env var being checked into the code repo accidentally.

The catch is who else can read them. Assume that processes on your computer can access the environment of other processes run by the same user. That includes the helper programs an agent starts. So an environment variable keeps a key out of Git, but it does not hide the key from software running as you.

06Moving a key out of an old .env file

You will probably start with a key in a plain file and want to move it. Do it in this order:

  1. Put the key in the new place, for example a Keychain item or your secrets manager.
  2. Start the app from the new place and check that it works.
  3. Delete the key from the old .env file, and make sure the file is in .gitignore.
  4. If the file was ever committed, pushed, shared in a chat or copied to a server, assume the key was exposed. Create a replacement, update your apps and revoke the old key, in that order.

Removing a key from a file does not make the old copy safe, because the old copy still works until you revoke it.

07Why agents change the picture

Where do I store API keys when an agent works on my Mac? Out of its reach as far as you can. A coding agent runs as you. Commands inside Claude Code's sandbox inherit its environment, secrets included. The default sandbox can read the whole computer except a few denied folders, and that default still allows reading credential files. In Claude Code's auto mode, reading .env and sending credentials to the matching API is allowed by default. So a key in a .env file is within reach of the agent, and of any malicious package it installs. The s1ngularity attack, a poisoned npm package, searched for .env files and SSH keys on macOS.

For containers, the rule is not to mount host secrets such as ~/.ssh or cloud credential files into them. Details for the agent side are in Claude Code and .env files and the sandbox guide.

08Habits that work with any option

  1. Never put secret keys in source code.
  2. Give each key an expiration date and rotate it on a schedule.
  3. Add a pre-commit hook that rejects commits containing keys. On macOS, brew install git-secrets installs one tool for this, and you must install its hooks in every repo with git secrets --install.
  4. Set a spend limit at the provider, so a stolen key has a ceiling.
  5. Do not reuse one key across projects, so a leak is easy to trace and revoke.

For a wider look at scanning your repos, see secret scanning. If a key has already escaped, the first-hour checklist tells you what to do in order.

09What to pick

For the fewest moving parts, use a .env file that is in .gitignore, and set a spend limit. With a team or many keys, use a secrets manager. Use the Keychain when you want a key on one Mac without a file. That is where to store API keys on a Mac. Whichever you choose, assume the Mac can be reached by something you did not invite, and keep every key short-lived and capped.

FAQ

Where should I put my API key?

Out of your code. Pass it to the app through an environment variable or a secrets manager. On a Mac that means a .env file that Git ignores, a Keychain item, or a secrets manager CLI.

What are the best practices for storing API keys?

Never put secret keys in source code. Keep .env files out of commits. Set an expiration date and rotate keys. Add a pre-commit hook that rejects commits containing keys.

Should API keys be kept secret?

Yes. Treat a key as account credentials, like a username and password. Bad actors continuously scan public repositories for keys.

Can I store my API key in an environment variable?

Yes. Passing keys through environment variables is the usual alternative to hard-coding them. One caution: processes on your computer can access the environment of other processes run by the same user.

How do I create an API key?

You create it in the provider's portal, the same place where keys are later managed and revoked. On OpenAI that is the API keys page of your account. Save the key when it is shown, because AWS shows the secret part only once.

Is the macOS Keychain safe for API keys?

It keeps the key out of a project file, but malware targets it too. AMOS, a Mac stealer that copies passwords and files, harvested Keychains from infected Macs. Keep spend limits and rotation in place as well.

Sources

  1. OpenAI docs, production best practices
  2. dotenv README
  3. Twelve-Factor App, config
  4. GitHub gitignore, Node template
  5. Git documentation, gitignore
  6. macOS security man page
  7. 1Password docs, secrets in environment variables
  8. Microsoft Defender Experts, hunting infostealers on macOS
  9. Microsoft Security blog, Contagious Interview
  10. Wiz, s1ngularity supply chain attack
  11. Trend Micro, AMOS variant
  12. Claude Code docs, sandboxing
  13. Claude Code docs, permission modes
  14. Stripe docs, API key best practices
  15. git-secrets README
  16. Artificial Immunity
Keys live on the Mac where your agents work. Artificial Immunity watches program starts there and reports what it finds.Get the free core