Secrets management for small engineering teams

Not every configuration value deserves the same protection. A public analytics identifier can ship in a browser bundle. A database password, payment API key, signing secret, or cloud service account key cannot. Start an inventory with the name, system, owner, environment, privilege, expiration or rotation expectation, and location of every credential. Classify by blast radius: read-only data, one tenant, one service, an entire database, or an entire cloud project. The classification determines how much access control and monitoring the secret needs.

Avoid calling all configuration secret. When everything is hidden, teams work around the process and paste real credentials into chat or tickets. Keep non-sensitive configuration easy to inspect while giving sensitive values a controlled path. A clear distinction also helps frontend engineers understand why a public environment variable is acceptable while a server-only key must never be imported into client code.

A .env file is useful for local development but is not a complete secrets-management system. Add local files to the ignore list, provide a documented example with placeholders, and scan commits and build artifacts for high-entropy strings. Check container layers, source maps, logs, crash reports, and generated bundles. Removing a secret from the latest commit does not remove it from history or from a container image that was already published.

When a credential is exposed, rotate it first and investigate second. Treat the old value as compromised even if you believe no one saw it. Record the exposure, affected systems, time window, and validation that the new credential works. Do not ask a teammate to paste the replacement into a shared channel. Use a direct secret-management path and confirm that the application has picked up the new version.

A managed secret store provides versioning, access policies, audit logs, and a controlled retrieval path. Grant the runtime identity access only to the specific secrets it needs. Separate development, staging, and production values, even when the names are similar. Avoid a single project-wide credential that every service can read. If a service is compromised, narrow permissions limit how far the incident can spread.

Decide when secrets are loaded. Loading at startup makes configuration predictable but may require a restart after rotation. Fetching on demand can reduce restart work but adds latency and a dependency on the store during requests. A short-lived in-process cache often balances the two. Whichever path you choose, handle missing and malformed values explicitly and fail closed for security-critical credentials.

Rotation fails when it is treated as an emergency-only procedure. For a credential that supports overlapping versions, create the new value, grant the runtime access, deploy code that can use it, verify traffic, and then revoke the old value. For a credential that cannot overlap, schedule a controlled maintenance window and test a rollback. Record who performed each step and which version the service observed.

Automate reminders and expiration alerts, but do not rotate blindly without a consumer test. A database password change can take down a worker that was not included in the main deployment. A webhook signing secret must overlap with the sender's rotation window. A cloud key should be replaced with workload identity when possible. The best rotation is the one that removes a long-lived credential rather than merely changing its text.

Secrets appear in logs more often than teams expect: authorization headers, connection URLs, stack traces, request dumps, and exception objects. Add redaction at the logging boundary and test it with representative errors. Redact by field name and by known secret value where possible, but do not rely on a single exact string because encodings and prefixes can differ. Never log a full request body from an endpoint that can contain credentials.

Operational tools should display metadata such as secret name, version, age, and owner without displaying the value. If an operator needs to verify a credential, use a scoped health check that reports success or a categorized failure. A health check should not echo the server response if that response might contain the secret. Make diagnostic modes temporary, access-controlled, and visible in audit logs.

Review who and what can read each secret. A service account used only for deployment should not automatically read production runtime credentials, and a developer's local identity should not be the application's production identity. Use separate roles for reading, writing, rotating, and administering. Review access after team changes and when a service is retired. An audit trail is useful only when someone owns the review.

Prefer short-lived credentials and identity-based access over static keys. Cloud workload identity, database roles, and provider-issued restricted keys reduce the number of values that need rotation. When a static key is unavoidable, limit its products, endpoints, IP ranges, and spending authority. Payment keys, webhook secrets, and database credentials should have different owners and different emergency procedures.

Provide a setup command or documented checklist that tells a new developer which non-sensitive values to copy and how to obtain local secrets without sharing them. Add a pre-commit or CI scan, but explain how to handle a false positive so engineers do not disable the scanner. Keep an example environment file current and mark which variables are client-visible. A predictable workflow is more effective than a policy that assumes everyone remembers every rule.

Secrets management is a system of habits: classify, store, scope, rotate, redact, audit, and rehearse. During an incident, use the inventory to find the affected credential, rotate it, verify consumers, and preserve evidence without spreading the value further. The goal is not perfect secrecy. It is limiting exposure and making recovery fast enough that a mistake does not become a prolonged breach.

Record which service account reads each secret, which deployment revision receives it, and when the value was last rotated without recording the value itself. Test a rotation in a staging path that exercises startup and live requests, then verify the previous version is no longer accepted. Access logs, expiry reminders, and a named owner turn secret management into an operational control that survives vacations, incidents, and team changes.

Create one secret per credential or tightly coupled configuration value, grant access to the runtime identity rather than individual developers, and reference a version from the deployment. Keep public browser configuration separate from server-only values. Record owner, purpose, rotation interval, and consuming service in a non-secret inventory.

Test startup with a missing secret, a denied service account, an expired version, and a successful rotation. Confirm that logs, client bundles, error pages, crash dumps, and analytics never contain the value. Compare the revision's secret version metadata with the approved deployment record without printing the secret itself.

Rotate on a schedule and after suspected exposure, use overlapping versions only for a defined window, and remove access when a service or team changes ownership. If a secret leaks, revoke or rotate it first, then inspect access logs and downstream use. Do not copy production credentials into a local `.env` file unless the file is protected and the access is explicitly necessary.

Use the cloud provider's Secret Manager IAM and rotation guidance, OWASP Secrets Management Cheat Sheet, and the service's threat model. Store the secret name and version policy in code, never the secret value.