TL;DR
|
An API key is a long, unique code that identifies you, or your app, to an online service. When your app asks the service for something, such as a reply from an AI model or a payment, it sends the key along, and the service checks it, does the work, and records the usage against your account.
If you've set up an AI coding tool, connected an app to an AI model, or added payments or maps to a website, you've been asked for one. This guide explains what API keys do, where to keep them, the common ways they leak, and what to do if yours does.
Key takeaway: an API key tells a service who's asking, so it can allow the request and charge the right account.
| Job | What it means |
|---|---|
| Identifies you | The service knows which account each request comes from |
| Grants access | Only requests with a valid key are accepted |
| Tracks usage | Requests are counted against your account |
| Bills you | Paid services charge your account for what the key uses |
| Limits usage | Services can cap how many requests a key can make |
Because a key is tied to your account and your bill, a stolen key can cost real money. A leaked AI model key, for example, can be used to run large workloads at your expense.
API keys are one of several ways to prove who's asking. Others include login tokens that expire, and OAuth, which lets you approve an app without sharing a password. API keys are popular because they're simple, which is also why they're easy to leak.
Key takeaway: keep keys out of your code, out of Git, and out of anything sent to the browser.
| Place | Safe? | Why |
|---|---|---|
| Written in your code | No | Anyone who can see the code can see the key, including everyone with access to the repository |
A .env file committed to Git | No | Git keeps the key in the history, even after you delete it |
A .env file kept out of Git | For local development | Fine on your own computer, as long as .gitignore excludes it |
| Environment variables on your server or platform | Yes | The key stays outside the code, and only the running app can read it |
| A secrets manager | Yes, for high-value keys | Keys are stored encrypted, access is controlled, and use is recorded |
| Browser code | Never, for secret keys | Every visitor can read it |
Our guides What are environment variables?, What is .env?, and What is a .gitignore file? cover each of these in detail.
Key takeaway: variables with these prefixes are copied into the code sent to every visitor's browser, so never use them for secret keys.
Front-end frameworks need a way to give browser code settings such as a public site address. They do it with special prefixes:
| Framework | Prefix | What happens |
|---|---|---|
| Next.js | NEXT_PUBLIC_ | The value is written into the JavaScript sent to the browser |
| Vite (used by React, Vue, and Svelte projects) | VITE_ | The value is written into the JavaScript sent to the browser |
| Create React App | REACT_APP_ | The value is written into the JavaScript sent to the browser |
So NEXT_PUBLIC_OPENAI_API_KEY isn't secret. Anyone can open the browser's developer tools and find it. This is a common leak in apps built quickly with AI tools, because putting the key in a public variable is the fastest way to make a front-end feature work.
The fix is to keep the secret key on the server. The browser calls your own server, and your server calls the outside service with the key. Some services also offer public keys designed for browsers, usually restricted to your website's address. Those are fine to expose, but check the service's documentation to be sure which kind you have.
Key takeaway: keys usually leak through ordinary mistakes, and automated bots find public ones quickly.
| How it leaks | Example |
|---|---|
| Committed to Git | A .env file or a hard-coded key pushed to a repository, especially a public one |
| Built into front-end code | A secret key in a NEXT_PUBLIC_ or VITE_ variable |
| Shared in chat or tickets | A key pasted into a support ticket, team chat, or forum post |
| Logs and error messages | An app that prints its settings, or an error page that shows them |
| AI coding tools | An agent reads a .env file and copies the key into code, a commit, or a pull request description |
| Screenshots and screen sharing | A key visible in a terminal or settings page during a demo |
Automated bots constantly scan public code for keys, so a key pushed to a public repository can be found and misused soon after. Many code hosts, including GitHub, scan for known key formats and can block or flag them, but don't rely on that alone.
Key takeaway: revoke the key first. Cleaning up the code comes after.
Deleting the key from your code or rewriting Git history doesn't undo a leak. Once a key has been public, assume someone has copied it, and treat the old key as burned.
Key takeaway: AI agents can read whatever is in your project folder, so keep real keys out of their reach where you can.
AI coding tools often need an API key themselves, and they work inside projects full of other keys. A few habits help:
.env files. Use test keys locally, and keep live keys on your hosting platform.Spending limits and usage caps also protect you if a key does leak. Our upcoming guide What is rate limiting? explains how limits protect apps and budgets.
Key takeaway: on Upsun Cloud, store API keys as sensitive variables, so they're available to your app but never in your repository.
Upsun Cloud apps read API keys from environment variables that you set on the platform, not from files in your code. According to the Upsun docs on variables:
| What to know | Details from the Upsun docs |
|---|---|
| Where keys go | Project variables for keys that are the same everywhere, or environment variables for keys that differ, such as test and live payment keys |
| Keeping them hidden | Mark them as sensitive. They're hidden in the Console and in command line output, but your app can still read them. Once sensitive, a variable can't be switched back |
| Reading them in code | The env: prefix makes the variable available as an ordinary environment variable, such as PAYMENT_API_KEY |
| Build vs runtime | You choose whether a variable is available during the build, at runtime, or both. Keep secret keys runtime-only unless the build genuinely needs them |
| Preview environments | Set the test key as a project variable and the live key on the main environment with inheritance turned off, so previews get the test key and only production gets the live one |
upsun variable:create --level project --name env:PAYMENT_API_KEY --value "sk_test_..." --sensitive true
upsun variable:create --level environment --environment main --name env:PAYMENT_API_KEY --value "sk_live_..." --sensitive true --inheritable false
Values in .upsun/config.yaml are committed to Git, so never put keys there. Our guide What are environment variables? covers how Upsun Cloud variables work in more depth.
You can deploy on Upsun Cloud free for 15 days, with no card needed, or see how security and compliance work on Upsun Cloud.
A secret code that lets an app use an online service on your behalf. The service uses it to know who's asking and which account to charge.
Not quite, but treat it like one. A password usually logs a person in. An API key lets an app or tool use a service, often with no other check.
In an environment variable on your server or hosting platform, or in a secrets manager. For local development, a .env file is fine if it's excluded from Git.
Only if the key is designed to be public. Those variables are built into code sent to every visitor's browser, so secret keys must stay on the server.
Revoke or rotate the key in the service's dashboard immediately, create a new one, update your apps, and check your usage for misuse. Removing it from the code alone isn't enough.
Yes. Many services bill usage to the account the key belongs to. Spending limits and usage alerts help limit the damage if a key is stolen.