AWS Secrets Manager Explained for Developers

AWS Secrets Manager stores credentials, API keys, and other sensitive strings so they never hard-code into repositories or environment files on disk. If you are new to the service, the mental model is simple: Secrets Manager is a vault with rotation hooks and fine-grained IAM access, integrated with RDS, Lambda, ECS, and CloudFormation.

This guide explains how Secrets Manager works, when to use it instead of Parameter Store, and the patterns that keep secrets out of logs and git history.

What problem Secrets Manager solves

Applications need database passwords, third-party API keys, and signing certificates. Common anti-patterns include:

• Committing .env files to git (even private repos leak eventually).
• Baking secrets into container images.
• Sharing one database password across every service and engineer.

Secrets Manager centralizes storage, encrypts values at rest with KMS, and delivers secrets to applications at runtime through IAM-authenticated API calls.

Core concepts

Secret

A named object holding either a plain string or structured JSON (for example username and password keys for RDS).

Version

Each update creates a new version. Applications can pin AWSCURRENT (default) or stage labels like AWSPENDING during rotation.

Rotation

Built-in rotation uses a Lambda function on a schedule to generate a new password, update the database, and flip the active version—without manual edits in config files.

Encryption

Secrets are encrypted with a KMS key you control. Key policies and IAM policies together define who can decrypt.

Secrets Manager vs Systems Manager Parameter Store

Both can hold secrets. Rough guidance:

Factor	Secrets Manager	Parameter Store (SecureString)
Automatic rotation	Native for RDS and custom Lambdas	Manual or custom
Pricing	Per secret per month + API calls	SecureString has cost at scale; standard params cheaper
Best fit	DB credentials, rotating keys	Config flags, non-rotating secrets, high volume low sensitivity

Many teams use Parameter Store for configuration and Secrets Manager for credentials that rotate or need audit trails.

Creating your first secret

Via AWS CLI:

aws secretsmanager create-secret \
  --name prod/myapp/database \
  --description "Primary Postgres credentials" \
  --secret-string '{"username":"app_user","password":"GENERATE_STRONG_PASSWORD"}'

Via console: choose Store a new secret, pick credential type (RDS integration wizard or other), and note the ARN.

Never echo secret values in CloudTrail unless you understand what gets logged; prefer retrieving secrets inside the runtime, not in CI logs.

Granting access with IAM

Applications should use task roles (ECS, Lambda, EC2 instance profile)—not long-lived access keys—to call secretsmanager:GetSecretValue.

Example policy fragment:

{
  "Effect": "Allow",
  "Action": ["secretsmanager:GetSecretValue"],
  "Resource": "arn:aws:secretsmanager:us-east-1:123456789012:secret:prod/myapp/database-*"
}

Scope resources tightly. "Resource": "*" is convenient in dev and expensive in audits.

Reading secrets from application code

Python example with boto3:

import boto3
import json

client = boto3.client("secretsmanager", region_name="us-east-1")

def load_db_config(secret_name: str) -> dict:
    response = client.get_secret_value(SecretId=secret_name)
    return json.loads(response["SecretString"])

config = load_db_config("prod/myapp/database")

Cache the value in memory for the process lifetime, but invalidate cache on rotation failures and support graceful reconnect when passwords change.

Node.js follows the same pattern with @aws-sdk/client-secrets-manager.

Rotation in practice

For Amazon RDS, Secrets Manager can manage master user rotation with a provided Lambda template. Custom secrets (API keys) need a rotation Lambda that:

1. Creates a new key at the provider.
2. Stores it as AWSPENDING.
3. Validates the new key against a health check.
4. Moves AWSCURRENT to the pending version.
5. Revokes the old key if applicable.

Rotation without health checks causes outages at 2 a.m.

CloudFormation and IaC patterns

Reference secrets by ARN, not value:

Environment:
  Variables:
    DB_SECRET_ARN: !Ref DatabaseSecret

Fetch at runtime inside the Lambda or container entrypoint. Injecting secret values directly into CloudFormation parameters defeats the purpose.

Networking and VPC considerations

GetSecretValue is a public AWS API call. From private subnets without NAT, use VPC interface endpoints for Secrets Manager so traffic stays on the AWS network and avoids public internet routing.

Monitoring and auditing

Enable CloudTrail data events for Secrets Manager in sensitive accounts. CloudWatch alarms on AccessDenied spikes can indicate misconfigured roles or credential stuffing against IAM.

Rotate KMS keys on a documented schedule if your policy requires it; re-encrypt secrets as AWS documents for key migration.

Common mistakes

1. Logging secret values in application info logs during debugging.
2. Granting developers personal IAM users broad secretsmanager:* in production.
3. Skipping rotation because "we will change it manually someday."
4. Storing huge blobs—Secrets Manager has size limits; use S3 with encryption for large artifacts.
5. One secret per environment mixed in one name—use prod/, staging/ prefixes and separate ARNs.

Cross-region and disaster recovery

Secrets are regional resources. Multi-region architectures replicate secrets manually or use AWS-provided replication where available. Document which region's secret ARN each deployment reads during failover drills—failover exercises often fail because staging still points at us-east-1 ARNs while traffic moved to eu-west-1.

For Aurora global databases, coordinate secret rotation with global cluster promotion order so secondary regions never hold stale credentials during a regional outage.

Integration with CI/CD

CI systems tempt teams to inject secrets as environment variables from a vault at build time. Prefer runtime retrieval in the deployed artifact's entrypoint:

• Build artifacts stay secret-free and safe to cache.
• Rotated secrets propagate without rebuilding images.
• Compromised build logs expose fewer credentials.

If CI must access secrets for integration tests, use short-lived OIDC roles to AWS rather than static keys in GitHub Actions secrets.

Local development without production secrets

Developers should use separate secrets per environment (dev/myapp/database vs prod/myapp/database). Never copy production passwords to laptops. Seed local databases with docker-compose env files gitignored at the repo root, documented in README setup steps.

Tools like AWS SSO plus temporary credentials help engineers run integration tests against staging secrets without standing admin access to production vaults.

Secrets Manager with Lambda and ECS sidecars

Lambda functions cold-start frequently; cache secrets outside the handler initialization block carefully—initialize once per execution environment. For ECS, some teams run a sidecar that writes secrets to a tmpfs file on startup; others fetch in the app directly. Sidecars add operational surface; direct SDK calls are simpler unless you need uniform injection across polyglot services.

Compliance mappings

For SOC 2 and ISO audits, document:

• Who can create, read, and rotate each secret class.
• Evidence of rotation schedules (CloudWatch Events rules).
• Break-glass procedures when rotation Lambda fails.

Auditors care about process more than which AWS service you picked.

FAQ

How much does Secrets Manager cost?
AWS charges per secret per month and per 10,000 API calls. High-churn microservices that fetch secrets on every request should cache aggressively.

Can Lambda read secrets without hardcoding the name?
Pass the secret ARN via environment variable. The execution role must allow GetSecretValue on that ARN only.

What is the difference between aws secrets manager and aws secret manager?
They refer to the same AWS service; searchers often use both spellings.

Should I use Secrets Manager for JWT signing keys?
Yes, when keys rotate or you need audit trails. Pair with KMS for asymmetric signing if your architecture requires HSM-backed keys.

Putting it together

Treat Secrets Manager as part of your credential lifecycle: create with strong randomness, deliver via IAM roles, rotate on schedule, and never print values to stdout. Combined with Parameter Store for non-secret config and VPC endpoints for private workloads, it removes the largest source of cloud breaches—secrets in source control—without slowing down development.