Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Secret

Pattern

A reusable solution you can apply to your work.

Also known as: Credential, Sensitive Data

Context

This is a tactical pattern. Systems depend on information that must stay confidential: passwords, API keys, encryption keys, tokens, private certificates, and database connection strings. A secret is any piece of information whose disclosure to an unauthorized party would let them do harm, whether that’s unauthorized access, data theft, impersonation, or worse.

In agentic coding workflows, secrets are everywhere. An AI agent may need API tokens to access services, SSH keys to interact with repositories, or database credentials to run queries. How these secrets are stored, transmitted, and scoped directly affects the security of the whole system.

Problem

Software needs secrets to function: to authenticate with databases, call APIs, sign tokens, and encrypt data. But secrets are dangerous precisely because they’re powerful. A leaked database password gives an attacker the same access as your application. A committed API key gives anyone who reads the repository full access to the associated service. How do you give your software the secrets it needs without creating unacceptable risk?

Forces

  • Secrets must be accessible to the software that needs them, but inaccessible to everyone else.
  • Developers need secrets during development, which creates pressure to store them in convenient but insecure places.
  • Secrets in version control are nearly impossible to fully remove. Git history is persistent.
  • Rotating secrets is disruptive but necessary; long-lived secrets accumulate risk over time.
  • AI agents need credentials to operate, but granting agents access to secrets introduces a new threat vector.

Solution

Follow a set of non-negotiable practices:

Never store secrets in source code or version control. Use environment variables, secret management services (like HashiCorp Vault, AWS Secrets Manager, or 1Password), or encrypted configuration files. If a secret is accidentally committed, rotate it immediately. Don’t just delete the commit, because the secret remains in git history.

Minimize secret lifetime. Short-lived tokens (minutes to hours) are safer than long-lived ones (months to never-expiring). Use token refresh mechanisms where possible. Rotate long-lived secrets on a regular schedule.

Scope secrets narrowly. An API key should grant only the permissions needed for its intended use, following least privilege. Don’t reuse the same secret across multiple environments or services.

Control access to secrets. Not every developer needs access to production credentials. Use role-based access to secret stores. Log who accesses which secrets and when.

Handle secrets carefully in agentic workflows. When an AI agent needs a secret, provide it through a secure mechanism (environment variables, a secrets API) rather than pasting it into a prompt. Be aware that agent conversation logs may be stored. Secrets included in prompts may end up in logs you don’t control.

How It Plays Out

A developer hardcodes a database connection string in a configuration file and commits it to a private repository. Months later, the repository is made public as part of an open-source initiative. The connection string is now exposed in the git history. An automated scanner finds it within hours. The database must be taken offline, the password rotated, and all services redeployed. Using a secrets manager from the start would have avoided the entire incident.

A developer sets up an AI agent to interact with a cloud provider. Instead of passing the cloud credentials in the prompt, they configure the agent’s environment with a scoped, short-lived session token loaded from a secrets manager. The agent can do its job, but the credentials aren’t visible in the conversation log, and the token expires after an hour.

Warning

If you paste a secret into a conversation with an AI agent, assume that secret is compromised. Conversation logs may be stored, cached, or used for training. Use environment variables or tool-based secret injection instead.

Example Prompt

“Move the database connection string out of the config file and into a secrets manager. Load it from an environment variable at runtime. Make sure the old hardcoded value is removed from the git history.”

Consequences

Good secret management reduces the impact of accidental exposure. Scoped, short-lived secrets limit what an attacker can do even if they obtain a credential. Centralized secret stores provide audit trails and make rotation manageable.

The costs include operational complexity (managing a secret store, configuring environments, handling rotation), developer friction (secrets aren’t as convenient as hardcoded values), and the risk of lockouts if the secret management system itself fails. But these costs are far smaller than the cost of a breach caused by leaked credentials.

  • Enables: Authentication. Secrets are the raw material of authentication.
  • Depends on: Least Privilege. Secrets should be scoped to minimum necessary access.
  • Uses: Trust Boundary. Secrets must not leak across trust boundaries.
  • Contrasts with: Attack Surface. Exposed secrets enlarge the effective attack surface.