Skip to content

Use a secret safely

Advanced  about 7 min

In this advanced exercise, you configure access credentials for external APIs using local environment files, load tokens securely in Python scripts, and verify that credentials never enter repository commits or session transcripts.

Before you start: A project managed in Git, and a dedicated, scoped API key for an authorized service (Setup). Never use primary personal credentials.

Background

The primary security objective is keeping authentication tokens out of source code, prompts, and version control (Secrets). The standard pattern is storing credentials in an environment variable, loaded locally from a .env configuration file excluded by .gitignore. The agent writes code to access the environment variable without ever reading or displaying the secret string.

General methodology

  1. Create the credential file directly: Initialize the configuration file outside the agent conversation so the secret string never enters the model context:
printf 'API_KEY=paste-your-token-here\n' > .env     # populate key in local text editor
chmod 600 .env                                     # restrict read/write permissions to user only
  1. Direct the agent to integrate the variable blindly:
Update scripts/<tool>.py to read API_KEY from environment variables (loading from .env via python-dotenv if present). Never print, echo, or log the key string to stdout or stderr. Verify that .env is explicitly listed in .gitignore. Do not open, read, or print the contents of .env.
  1. Verify isolation: Confirm that git status ignores .env, search repository files for the secret string, and run the script to confirm successful API authentication.

Append a standing security rule to AGENTS.md: "Never print, log, or commit authentication credentials; do not inspect .env."

Workshop example · Clinical: clinic network

Start from: the committed project from the previous step (how to restore)
Produces: .env (ignored), a tool that reads the key

Prompt

Make scripts/classify_notes.py (a stub for now) read LLM_API_KEY from the environment, loading it from .env if present. Never print or log it. Make sure .env is in .gitignore. Do not open or display .env. Then run `git status` and show me the result.

Used in: the bulk-classification step, which needs a key for a language-model service. Use a key your institution approves for the data you will send (Privacy). The visit notes in this material are synthetic, so any approved endpoint works.

What you should see. git status does not list .env. The script exits with a message such as "LLM_API_KEY is not set" when the file is absent.

Test the guard. Temporarily rename .env, run the script, and confirm the clear failure. Then restore it.

Verification criteria

  • Git exclusion verified: The .env file does not appear in git status and file permissions are restricted (chmod 600).
  • Zero credential leakage: The secret string does not appear in any committed file, transcript log, or console output.
  • Graceful error handling: The script fails with an informative error message if the environment variable is absent.

Incident response for credential exposure

If a credential is inadvertently printed to console output or committed to Git, immediately revoke and rotate the token within the provider management console before cleaning repository history (Secrets).

Concepts behind this

  • Secrets. Credentials must never enter prompts, session logs, or version control. Use isolated environment variables and enforce immediate revocation protocols if exposed. Go deeper →
  • Tools. Turning interactive prompts into parameterized scripts creates deterministic, testable tools that run identically on every execution. Go deeper →
  • Version control. Version control provides an immutable audit trail and safety net, allowing researchers to inspect every line changed by an agent and roll back errors instantly. Go deeper →

Builds on: Review and commit what the agent produced