Neura Market Logo

Secret Placeholder Conventions for Safe Documentation Examples

Learn how to write secret-scanner-safe placeholders in docs and examples. This guide helps developers avoid accidentally exposing real credentials in code snippets.

Read this when

  • Writing docs that include tokens, API keys, or credential snippets
  • Updating examples that may be scanned by secret-detection tooling

Secret placeholder conventions

Choose placeholders that are easy to read but clearly not actual secrets.

  • Favor descriptive values such as example-openai-key-not-real or example-discord-bot-token.
  • In shell snippets, use ${OPENAI_API_KEY} instead of inline strings that look like tokens.
  • Keep examples obviously fake and tailored to their context (provider, channel, auth type).

Avoid these patterns in docs

  • Literal PEM private key header or footer text.
  • Prefixes that look like real credentials, for example sk-..., xoxb-..., or AKIA....
  • Bearer tokens that appear realistic and were copied from runtime logs.

Example

# Good
export OPENAI_API_KEY="example-openai-key-not-real"

# Better (when the doc is about env wiring)
export OPENAI_API_KEY="${OPENAI_API_KEY}"