What Is AWS Secrets Manager? How It Works and When to Use It

Simple explanation

Think of Secrets Manager as a secure vault with an API. You put a secret in (a database password, an API key, an OAuth token), and your application retrieves it at runtime by asking for it by name. The secret is encrypted at rest, access is controlled by IAM, and every retrieval is logged.

A secret is any piece of information that would give an attacker access to a system if exposed. Database passwords, private keys, API tokens, and connection strings are all secrets.

Storing secrets in source code, Git repositories, container images, environment variable files committed to version control, or shared documents is dangerous. Anyone with access to the repo, the image, or the document has the credentials. Secrets Manager eliminates that risk by separating where the secret lives from where it is used. For more on why hardcoded credentials create real incidents, see why long-lived access keys are dangerous.

Why this matters

Leaked credentials are one of the most common causes of security breaches in cloud environments. The risks are concrete:

• Hardcoded database passwords get committed to Git. Anyone who clones the repo has production access.
• API keys in config files end up in container images, build logs, or error messages.
• Manual password rotation causes outages when one application still uses the old password.
• Shared credentials make it impossible to revoke access for one application without breaking others.
• No audit trail means you cannot tell who accessed a credential or when.

Secrets Manager addresses all of these problems. Credentials live in an encrypted store, applications fetch them at runtime, rotation happens automatically, each application gets its own credential, and every access is logged in CloudTrail.

How AWS Secrets Manager works

Here is the conceptual flow from storing a secret to an application using it:

1. Store the secret. You create a secret in Secrets Manager with a name (e.g., prod/myapp/database) and a value (the JSON or string containing the credential).
2. Encrypt with KMS. Secrets Manager encrypts the value using a KMS key. By default it uses the AWS-managed key aws/secretsmanager. You can specify a customer managed key for compliance or cross-account access.
3. Control access with IAM. You attach an IAM policy to the application’s role granting secretsmanager:GetSecretValue on the specific secret ARN. You can also attach a resource-based policy to the secret itself.
4. Application fetches at runtime. The application calls GetSecretValue via the AWS SDK. KMS decrypts the value server-side, and the plaintext secret is returned over TLS.
5. Optionally rotate. Secrets Manager invokes a Lambda function on a schedule to generate a new credential, update the target service (e.g., change the RDS password), and store the new value.
6. Application refreshes. On the next fetch, the application receives the new credential. Applications that cache secrets should use short TTLs and retry with a fresh fetch on authentication failure.

What you can store in Secrets Manager

A secret in Secrets Manager is a name that maps to a JSON document or a plain string, up to 65 KB. Common types:

• Database credentials including username, password, host, port, and database name (used with RDS, Aurora, Redshift, DocumentDB)
• API keys for third-party services like payment providers, SaaS platforms, and messaging services
• OAuth client secrets and tokens such as client IDs, client secrets, and refresh tokens for service integrations
• TLS/SSL certificates and private keys for services that need to present or validate certificates
• Application secrets like signing keys, encryption keys, webhook secrets, and SMTP credentials

Secrets are encrypted at rest using KMS. For details on how encryption keys work across AWS services, see encryption in AWS.

When to use Secrets Manager

Secrets Manager is the right choice when:

• The credential needs automatic rotation, such as database passwords or API keys that expire
• You are storing RDS, Aurora, Redshift, or DocumentDB credentials where built-in managed rotation is available
• Third-party API keys that must be audited and access-controlled
• Secrets consumed by Lambda, ECS, EKS, or EC2 applications at runtime
• You need cross-account secret sharing with resource-based policies
• Credentials used in CI/CD pipelines that should not be stored in pipeline config. See secrets in CI/CD pipelines
• Compliance requires audit logging of every credential access

When not to use Secrets Manager

Secrets Manager costs $0.40 per secret per month plus $0.05 per 10,000 API calls. It is not the right tool for everything:

• Non-sensitive configuration values like endpoint URLs, feature flags, S3 bucket names, and region settings. Use SSM Parameter Store (free standard tier).
• Feature flags and application config. AWS AppConfig or SSM Parameter Store are purpose-built for this.
• Static settings that never change. If the value will not rotate and is not sensitive, Parameter Store is simpler and free.
• High-volume lookups of non-secret data. The per-call pricing adds up quickly for data that does not need encryption or rotation.

Secrets Manager vs SSM Parameter Store

Choose Secrets Manager when the credential rotates, needs cross-account sharing via resource policy, or requires the audit trail and lifecycle management that comes with a dedicated secrets service.

Choose Parameter Store when the value is non-sensitive config, a static secret that rarely changes, or when you want to avoid the per-secret monthly cost. Parameter Store’s free standard tier handles most configuration needs.

Creating and retrieving secrets

Create a secret via CLI

# Create a database credential secret
aws secretsmanager create-secret \
  --name "prod/myapp/database" \
  --description "Production RDS credentials for MyApp" \
  --secret-string '{"username":"myapp_user","password":"<generated-password>","host":"mydb.cluster-xxxx.us-east-1.rds.amazonaws.com","port":5432,"dbname":"myapp_prod"}'

Retrieve a secret via CLI

# Get the secret value as formatted JSON
aws secretsmanager get-secret-value \
  --secret-id "prod/myapp/database" \
  --query 'SecretString' --output text | python3 -m json.tool

Retrieve a secret in Python

import boto3
import json

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

    response = client.get_secret_value(SecretId="prod/myapp/database")
    secret = json.loads(response["SecretString"])

    return {
        "host": secret["host"],
        "port": secret["port"],
        "database": secret["dbname"],
        "user": secret["username"],
        "password": secret["password"],
    }

Retrieve a secret in Node.js

const {
  SecretsManagerClient,
  GetSecretValueCommand,
} = require("@aws-sdk/client-secrets-manager");

const client = new SecretsManagerClient({ region: "us-east-1" });

async function getDatabaseCredentials() {
  const command = new GetSecretValueCommand({
    SecretId: "prod/myapp/database",
  });
  const response = await client.send(command);
  return JSON.parse(response.SecretString);
}

Each application that retrieves a secret needs an IAM role with permission scoped to the specific secret ARN. For background on how IAM policies work, see IAM policy structure.

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

Access control and encryption

Access to a secret is controlled at three layers:

1. IAM identity policies. The application’s IAM role must have secretsmanager:GetSecretValue (and optionally secretsmanager:DescribeSecret) scoped to the specific secret ARN. Follow least privilege and never use "Resource": "*" for secret access.
2. Resource-based policies. You can attach a policy directly to the secret to grant or deny access from specific principals, accounts, or VPC endpoints. This is how cross-account access works. You can use IAM policy conditions to restrict access further, for example limiting access to requests from a specific VPC endpoint.
3. KMS key policies. The KMS key used to encrypt the secret must also allow the calling principal to perform kms:Decrypt. If you use the default AWS-managed key (aws/secretsmanager), this is handled automatically within the same account. For cross-account access or tighter control, use a customer managed key and grant decrypt permissions explicitly in the key policy.

Rotation explained

Rotation is the process of periodically replacing a secret’s value with a new one: generating a new password, updating it in the target service, and storing the new value in Secrets Manager. This limits the window of exposure if a credential is compromised.

Managed rotation vs custom rotation

Managed rotation is available for supported AWS databases: Amazon RDS (MySQL, PostgreSQL, MariaDB, Oracle, SQL Server), Aurora, Redshift, and DocumentDB. When you enable rotation for one of these, Secrets Manager provisions the Lambda function for you. You configure the schedule and the rotation strategy. You do not write the function.

Custom rotation is for everything else: third-party API keys, non-AWS databases, service accounts, and tokens. You write a Lambda function that implements the four-step rotation interface and tell Secrets Manager to invoke it on schedule.

The four-step rotation workflow

Every rotation Lambda, whether managed or custom, follows four steps:

1. createSecret: Generate a new credential and store it in Secrets Manager as a new version with the staging label AWSPENDING.
2. setSecret: Update the target service (e.g., change the database password) with the new credential.
3. testSecret: Verify the new credential works by connecting to the target service using the AWSPENDING version.
4. finishSecret: Move the staging label AWSCURRENT to the new version and AWSPREVIOUS to the old version.

If any step fails, the rotation stops and the AWSCURRENT version remains unchanged. The old credential keeps working. For a deeper walkthrough, see rotating secrets automatically in AWS.

What applications must do to survive rotation

Rotation changes the credential in the target service. Applications must be able to handle this:

• Do not cache secrets indefinitely. Use a short cache TTL (the AWS Secrets Manager caching client defaults to 300 seconds). If your application reads the secret once at startup and never refreshes, it will fail after rotation.
• Implement retry on authentication failure. When a connection fails with an authentication error, re-fetch the secret from Secrets Manager and retry. This handles the brief window during rotation when the old credential may already be replaced.
• Use the AWS caching clients. AWS provides caching libraries for Python, Java, .NET, and Go that handle TTL-based caching and automatic refresh. Use them instead of building your own caching logic.