TokenTonic

Home / Token Security Practices

Token security practices

Real tokens are passwords that travel in every request. Here is the practical hygiene that keeps them safe.

Guide · TokenTonic

A leaked API key is one of the most common — and most preventable — security incidents in software. The practices below are not exotic; they are the unglamorous basics that stop the majority of credential leaks. (Mock tokens from TokenTonic need none of this, which is exactly why they exist — but practice the same hygiene with them anyway, so the habits are automatic.)

1. Environment variables, not code

Secrets live in the environment, never in source code. The pattern:

  • Read keys from environment variables (process.env.API_KEY, os.environ) at startup.
  • Keep a .env.example file with placeholder values so new developers know what to set — and add .env to .gitignore on day one.
  • In production, use your platform's secrets manager (AWS Secrets Manager, HashiCorp Vault, or your host's env-var store), not files on disk.

2. Git hygiene

Keys end up in git more often than anywhere else. Defenses, in order of effectiveness:

  1. Never commit them in the first place — .gitignore your .env, and review diffs before pushing.
  2. Use pre-commit hooks that scan for key-like patterns (tools like gitleaks or truffleHog).
  3. Enable secret scanning on your hosting platform — GitHub's secret scanning recognizes many providers' key prefixes (another reason prefixes like sk- exist) and can alert you automatically.
  4. If a key leaks, rotate it immediately. Removing it from git history is not enough — assume it is compromised the moment it was pushed.

3. Rotation on a schedule

Long-lived keys should be rotated — quarterly is a common cadence, and immediately after any suspected exposure or team departure. Design for rotation from the start: support overlapping old/new keys during a transition window, and make rotation a runbook procedure rather than a fire drill.

4. Least privilege and short lifetimes

  • Scope tokens narrowly. A token that only needs read access should not have write. Most providers support scoped keys — use them.
  • Prefer short-lived tokens. OAuth access tokens that expire in an hour limit the damage of any single leak. Long-lived keys should be the exception, closely guarded.
  • Separate keys per environment. Development, staging and production each get their own keys, so a dev-machine compromise cannot touch production.

5. Never in URLs, logs or screenshots

Tokens travel in the Authorization header — not in URL query parameters (URLs get logged by proxies, browsers and analytics), not in application logs, and not in screenshots or screen shares. When debugging auth issues, log the token's prefix and last few characters for identification, never the whole thing.

6. Treat mock tokens with respect too

Mock tokens grant nothing, but sloppy handling of them trains sloppy handling of real ones. Do not paste mock tokens into production configs "just for now", do not commit them to real repos, and label them clearly. The discipline is the point: the day you are tired and in a hurry, the habit is what saves you.

The one-line version: real tokens live in secrets managers, travel only in headers, die young, and get replaced the moment they might have leaked. Everything else is commentary. For the test-data side of the equation, generate mock tokens any time you need realistic fixtures.

Related guides