Show an API key in docs as an unmistakable placeholder, such as YOUR_API_KEY, and read it from an environment variable in the sample. Never paste a real key, and avoid strings that look real, because readers copy them, scanners flag them and someone eventually pushes a live value by habit.
Why the example is where leaks start
A tutorial teaches by showing a complete line of code. If that line contains a literal key, readers learn to put keys in code. The Twelve-Factor App guidance describes a litmus test for config: could the codebase be made open source at any moment without compromising credentials? A sample that hardcodes a key fails that test on page one.
There is a second problem. A realistic fake key looks like a real one to reviewers and tools. Teams then waste time triaging false alarms, or worse, learn to ignore them.
Three patterns, compared
| Pattern | Reader outcome | Risk |
|---|---|---|
| Literal realistic string in the code | Copies the habit of hardcoding | High: the habit spreads, alerts become noise |
| Obvious placeholder in the code | Replaces it, may still commit it | Medium: a pasted real key lands in source |
| Environment variable read in the code | Sets the variable outside the file | Low: the key never enters the file |
The third pattern is the one to teach. It also matches how deployment works, because config that varies between staging and production should live outside the code.
A sample that teaches the habit
import os
import requests
api_key = os.environ["EXAMPLE_API_KEY"]
response = requests.get(
"https://api.example.com/v1/items",
headers={"Authorization": "Bearer " + api_key},
timeout=10,
)
print(response.status_code)
Beside it, show how to set the variable for one shell session, and tell readers where the real value comes from. Use a hostname reserved for examples so a copied request goes nowhere real.
Steps for docs owners
- Decide one placeholder style and use it everywhere, for example
YOUR_API_KEYin prose and an environment variable in code. - Make placeholders fail loudly. A sample that raises a clear error when the variable is missing is better than one that sends an empty header.
- Never use a working test key in a public sample, even a rate limited one. Test keys get abused and are hard to retire once printed in a thousand blog posts.
- Add
.envto the ignore file in every sample repository, and commit a template file with empty values. - State what the real key can do, and tell readers to use the narrowest scope available.
- If a real key is ever published, treat it as exposed: revoke it first, then clean up. The post on what to do when a sample repo commits a real secret covers the order of steps.
Try it yourself
See how a static analysis pass reads code and reports risky patterns.
Click through it at your own pace, or open it full screen.
For the broader practice, see what to commit and what to ignore in an env example file.
Safeguard's code and dependency scanning can run over the sample repositories your docs ship, and gates can block a pull request that breaks your policy. You can also try the free scan at https://gold.safeguard.sh/scan.
Quick check
Is a fake key that looks real fine in docs?
It is better to avoid it. Real looking strings train readers to hardcode keys and trigger alerts that people learn to ignore. An obvious placeholder is clearer.
Should a docs sample include a working test key?
No. Public test keys get abused and are difficult to retire. Tell readers how to get their own key instead.
Sources
Last reviewed: 19 October 2026.
