AWS Secrets Manager: everything you need to know [2026]

AWS Secrets Manager is an AWS service that stores, encrypts, retrieves and rotates database credentials, API keys, OAuth tokens and other secrets, so your code fetches them at runtime instead of hard-coding them.

This covers creating and reading a secret, how encryption and rotation work, Region replication, pricing as of October 2026, quotas, the alternatives, and fixes for the errors AWS documents.

How to use AWS Secrets Manager: store your first secret

Your IAM identity needs the permissions in the SecretsManagerReadWrite managed policy. The console is the quickest way to store a secret.

1. Open the Secrets Manager console at https://console.aws.amazon.com/secretsmanager/ in the Region where your app runs.
2. Choose Store a new secret.
3. Under Secret type, pick the database credential type for a database, or Other type of secret for API keys and tokens.
4. Enter the values as Key/value pairs, or switch to the Plaintext tab and paste any format up to 65,536 bytes.
5. Leave Encryption key on aws/secretsmanager unless you need cross-account access or your own key policy, then choose Next.
6. Type a Secret name (1-512 characters: letters, numbers and /_+=.@-) and a Description, then choose Next.
7. Leave rotation off for now on Configure rotation, choose Next, review the details and choose Store.

Choose the refresh button if the new secret does not appear in the list straight away. Do not put sensitive data in tags, because tags are not encrypted.

What is AWS Secrets Manager and what does it do?

Secrets Manager replaces a password in source code with a runtime call that fetches it. Anyone who can read the code, the container image or the config file no longer sees the credential.

Core feature	What it does
Encrypted storage	Encrypts every secret value at rest with an AWS KMS key and sends it to you over TLS
Runtime retrieval	Apps, Lambda functions, containers and CI jobs fetch the current value through the API, SDKs or CLI
Automatic rotation	Changes the credential on a schedule as often as every four hours, in the secret and in the database or service
Versioning	Keeps the current, previous and pending versions with the labels AWSCURRENT, AWSPREVIOUS and AWSPENDING
Access control	IAM policies, resource policies on each secret and attribute-based access control decide who can read or change it
Multi-Region replication	Copies a secret to other Regions and keeps replicas in sync with the primary
Auditing	Logs every create, read, rotate and delete call to AWS CloudTrail
Managed secrets	Amazon RDS, Aurora, Redshift and other services create and rotate their own admin secrets for you

AWS points other secret types to other services: AWS credentials to IAM, encryption keys to AWS KMS, SSH keys to EC2 Instance Connect, and private keys and certificates to AWS Certificate Manager.

How does AWS Secrets Manager work?

Each secret is a value plus metadata. The value is encrypted with envelope encryption, and every change creates a new version.

Stage	What happens
You store or change a value	Secrets Manager asks AWS KMS for a new 256-bit AES data key, encrypts the value with it outside KMS, and keeps only the encrypted copy of the key
The secret gets an ARN	Format arn:aws:secretsmanager:<Region>:<AccountId>:secret:SecretName- plus six random characters, so a recreated secret never inherits the old one's access
An app asks for the value	Secrets Manager checks IAM and resource policies, has KMS decrypt the data key, decrypts the value and returns it over TLS
Rotation runs	A new version is written with the AWSPENDING label, tested, then moved to AWSCURRENT while the old one becomes AWSPREVIOUS
Old versions pile up	Unlabelled versions are deprecated and removed once a secret has more than 100, but never within 24 hours of creation
Every call	CloudTrail records it as a management event

None of the Secrets Manager APIs return the encrypted secret or the encrypted data key. A retrieval returns the AWSCURRENT version unless you ask for another stage.

How do I access AWS Secrets Manager: console, CLI, SDK or API?

Access route	Use it when	Note
Secrets Manager console	You manage a few secrets by hand	Almost every task is available in the browser
AWS CLI	You script tasks or work from a terminal	Commands sit under aws secretsmanager; shell history can capture secret values
AWS Tools for Windows PowerShell	You automate from PowerShell on Windows	Second official command-line tool set
AWS SDKs	Your application reads secrets at runtime	C++, Go, Java, JavaScript, Kotlin, .NET, PHP, Python (Boto3), Ruby, Rust, SAP ABAP and Swift; requests are signed and retried for you
HTTPS Query API	You cannot use an SDK	Call secretsmanager.<region>.amazonaws.com directly and sign every request yourself
Lambda extension	A Lambda function needs secrets	The AWS Parameters and Secrets Lambda Extension fetches and caches values without an SDK

Endpoints support IPv4 and IPv6, TLS 1.2 and 1.3, and post-quantum TLS in every Region except the China Regions. FIPS endpoints exist in some Regions.

Get a secret value with the AWS Secrets Manager CLI

The caller needs the secretsmanager:GetSecretValue permission. Replace MyTestSecret with your secret's name or full ARN.

aws secretsmanager get-secret-value --secret-id MyTestSecret

Returns the AWSCURRENT version of the secret. Add --version-stage AWSPREVIOUS to read the version that was current before the last rotation.

You should see: A JSON block with ARN, Name, VersionId, SecretString, VersionStages showing AWSCURRENT, and CreatedDate.

To read several secrets in one call, use aws secretsmanager batch-get-secret-value --secret-id-list MySecret1 MySecret2. It needs secretsmanager:BatchGetSecretValue plus GetSecretValue on each secret.

AWS Secrets Manager CLI commands: create, list, describe and delete secrets

Replace MyTestSecret with your own secret name or ARN. If you run the AWS CLI in the Windows Command Prompt, quoting rules for JSON differ from Linux and macOS, so passing the value from a file with file:// avoids escaping problems.

Task	Command
Create a secret from a JSON file	aws secretsmanager create-secret --name MyTestSecret --secret-string file://mycreds.json
List secrets in the Region	aws secretsmanager list-secrets
List secrets with Test in the name	aws secretsmanager list-secrets --filters Key="name",Values="Test"
Show a secret's metadata	aws secretsmanager describe-secret --secret-id MyTestSecret
Replicate to another Region	aws secretsmanager replicate-secret-to-regions --secret-id MyTestSecret --add-replica-regions Region=eu-west-3
Schedule deletion after 7 days	aws secretsmanager delete-secret --secret-id MyTestSecret --recovery-window-in-days 7
Cancel a scheduled deletion	aws secretsmanager restore-secret --secret-id MyTestSecret

Typing a password straight into --secret-string leaves it in shell history. AWS recommends writing it to a file, passing the file, then deleting the file.

AWS Secrets Manager rotation: turn on automatic rotation

These steps cover rotation by Lambda function for a non-database secret. You need iam:CreateRole and iam:AttachRolePolicy, and a Lambda rotation function, which you can deploy from the SecretsManagerRotationTemplate application in the Lambda console where AWS Serverless Application Repository is supported.

1. Open the Secrets Manager console and choose your secret on the Secrets page.
2. In the Rotation configuration section, choose Edit rotation.
3. Turn on Automatic rotation.
4. Under Rotation schedule, use the Schedule expression builder or type a Schedule expression such as rate(30 days); times are UTC.
5. Optionally set Window duration, for example 3h, so rotation only runs inside that window.
6. Select Rotate immediately when the secret is stored if you want the first rotation now rather than on schedule.
7. Under Rotation function, choose your Lambda function, then choose Save.

The function's execution role needs access to the secret and the target service, and the function's resource policy must grant lambda:InvokeFunction to Secrets Manager. AWS recommends the aws:SourceAccount condition key there.

AWS Secrets Manager rotation types and schedules explained

Rotation type	Used for	Lambda function?
Managed rotation	Admin credentials created by Amazon RDS, Aurora, DocumentDB and Redshift, plus Amazon ECS Service Connect TLS certificates	No; usually completes within one minute
Managed external secrets	Secrets held by Secrets Manager partner applications	No
Rotation by Lambda function	Every other secret, including your own databases and third-party API keys	Yes, billed at Lambda rates

A Lambda rotation runs four steps: create_secret, set_secret, test_secret and finish_secret. If a step fails, Secrets Manager retries the whole rotation during the open rotation window.

Schedules use rate() or cron() expressions, from every four hours up to 999 days, with a window of at least one hour. Single user and alternating users are the two Lambda strategies, and AWS suggests alternating users for application logins that need the highest availability.

Replicate AWS Secrets Manager secrets to another Region

Secrets are regional. Replication copies the encrypted value, tags and resource policies to other enabled Regions, and rotation in the primary Region updates every replica.

1. Open the Secrets Manager console and choose your secret.
2. On the Replication tab, choose Replicate secret, or Add Region if it already has replicas.
3. In Add replica regions, pick the AWS Region.
4. Optionally choose an Encryption key that lives in the replica Region.
5. Choose Replicate and watch Replication status for each Region on the details page.

A replica's ARN matches the primary except for the Region. GovCloud (US) and China Regions can only replicate among themselves, and you can still read a secret from another Region without replicating it by calling that Region's endpoint.

AWS Secrets Manager integrations with Lambda, RDS, EKS and Parameter Store

Service or tool	How it uses Secrets Manager
Amazon RDS, Aurora, Redshift, DocumentDB	Create and rotate their own admin secrets as managed secrets
AWS Lambda	Reads cached secrets through the AWS Parameters and Secrets Lambda Extension; needs a VPC endpoint when the function runs in a VPC
Amazon EKS, ECS and EC2	EKS workloads can retrieve secrets directly; the AWS Workload Credentials Provider standardises secret use across Lambda, ECS, EKS and EC2
AWS Systems Manager Parameter Store	References a Secrets Manager secret as a parameter; the secret ID needs a leading forward slash
AWS CloudFormation and AWS CDK	Create secrets and rotation as part of your infrastructure templates
GitHub and GitLab jobs, AWS Batch, IoT Greengrass	Retrieve secrets during builds, batch jobs and on edge devices
Amazon EventBridge, AppFlow, DataSync, Direct Connect	Store their connection secrets in Secrets Manager under a service ID prefix such as events or appflow
AWS CloudTrail, CloudWatch, Config, GuardDuty	Log, alarm on, audit and watch secret access for threats

AWS Secrets Manager pricing and cost examples

Prices below are from the AWS pricing page as checked on 9 October 2026. You pay per secret stored and per API call, with no upfront fee.

Cost item	Price (October 2026)
Each secret	$0.40 per secret per month, prorated by the hour for short-lived secrets
API calls	$0.05 per 10,000 calls
New versions created by rotation	No charge
Secrets scheduled for deletion	No charge
AWS managed key aws/secretsmanager	No charge
Customer managed KMS key	$1 per key per month plus KMS request charges after 20,000 free requests a month
Lambda rotation function	Standard Lambda pricing
Example: 15 secrets, about 4,040 calls a month	$6.02 a month
Example: 1,500 secrets used 20 times a day	$604.50 a month

Use cost allocation tags on secrets to split the bill by project, and the AWS Pricing Calculator to estimate a full architecture.

AWS Secrets Manager vs Parameter Store vs KMS: which to use

These services overlap, but AWS's own guidance draws clear lines between them.

Your situation	Use this	Why
Database credentials, API keys or tokens that should rotate	AWS Secrets Manager	Only option with automatic rotation, native database integrations and cross-Region replication
Plain configuration such as endpoint URLs or AMI IDs	Parameter Store standard parameters	No extra charge, up to 10,000 parameters of 4 KB each per Region
Encrypted config that never rotates	Parameter Store SecureString	KMS encryption without per-secret fees; advanced parameters cost $0.05 each a month
Encryption keys for your own data	AWS KMS	KMS holds keys and does crypto operations; it does not store app credentials
AWS access for code running on AWS	IAM roles	Temporary credentials at no extra cost, with nothing to store
Workload runs on Microsoft Azure	Azure Key Vault	Azure's own store for secrets, keys and certificates

AWS Secrets Manager security best practices

Practice	How to apply it
Remove hard-coded secrets	Scan code with the Amazon CodeGuru Reviewer secrets detector or Amazon Q, then move what it finds into Secrets Manager
Pick the right key	Use aws/secretsmanager by default; use a customer managed key with kms:ViaService set to secretsmanager.<region>.amazonaws.com for cross-account access
Grant least privilege	Scope IAM and resource policies to named secrets, and require secretsmanager:BlockPublicPolicy on PutResourcePolicy
Rotate	Turn on automatic rotation; use a low-privilege app user and alternating users rather than the master user
Cache values	Use the client-side caching libraries for Java, Python, .NET, Go or Rust instead of calling the API on every request
Keep traffic private	Reach Secrets Manager through an interface VPC endpoint and restrict with aws:SourceVpc or aws:SourceVpce
Be careful with IP conditions	An aws:SourceIp rule can block Lambda rotation, which calls from AWS-internal addresses
Monitor	Log with CloudTrail, alarm in CloudWatch, check compliance with AWS Config and detect threats with GuardDuty

AWS Secrets Manager use cases

Use case	How Secrets Manager fits
Web app database passwords	The app refreshes its connection pool from the secret, and weekly rotation changes the password without a redeploy
Short-lived tokens for microservices	Store tokens for an hour at a time; per-secret cost is prorated hourly
Third-party API keys and OAuth tokens	One encrypted, audited place instead of keys spread across config files
Cross-account access	A customer managed KMS key plus a resource policy lets another AWS account read the secret
Multi-Region disaster recovery	Replicas keep credentials available in a standby Region
CI/CD pipelines	GitHub or GitLab jobs fetch deploy credentials at run time instead of storing them in the repository

AWS Secrets Manager limits, quotas and limitations

Limit	Default value	Adjustable?
Secrets per Region per account	500,000	No
Secret value size	65,536 bytes	No
Versions per secret	100	No
Staging labels across all versions	20	No
Resource policy length	20,480 characters	No
GetSecretValue requests	10,000 per second	No
DescribeSecret requests	40,000 per second	No
ListSecrets and BatchGetSecretValue requests	100 per second each	No
CreateSecret, DeleteSecret and most write calls	50 per second	No

Other limits worth planning for: the minimum rotation interval is four hours, a deleted secret stays recoverable for at least seven days unless you force deletion, and you cannot delete a primary secret while replicas exist. Cross-account calls count against the caller's account, not the owner's.

Delete an AWS Secrets Manager secret immediately or restore it

Deletion is deliberately slow. By default a deleted secret becomes inaccessible at once but stays recoverable for a 7 to 30 day window, 30 days if you set nothing.

1. Delete any replicas first: open the primary secret, choose the replica under Replicate Secret, then Actions > Delete Replica.
2. Open the secret, choose Actions > Delete secret.
3. Enter the Waiting period in days and choose Schedule deletion.
4. To delete with no recovery window, run aws secretsmanager delete-secret --secret-id MyTestSecret --force-delete-without-recovery instead; this cannot be undone.
5. To restore, choose Preferences, select Show secrets scheduled for deletion, open the secret and choose Cancel deletion twice.

If you are unsure whether anything still uses the secret, set a CloudWatch alarm on access attempts during the recovery window. Deleting needs secretsmanager:ListSecrets and secretsmanager:DeleteSecret.

Check that an AWS Secrets Manager secret and rotation work

1. Run aws secretsmanager get-secret-value --secret-id MyTestSecret with the same role your app uses.
2. Confirm the output has a SecretString with your keys and VersionStages showing AWSCURRENT.
3. After a rotation, run the same command with --version-stage AWSPREVIOUS and confirm it returns the older value.
4. Run aws secretsmanager describe-secret --secret-id MyTestSecret to review the secret's metadata, including any owning service.
5. Open CloudTrail event history and check for the GetSecretValue or RotateSecret events you expect.

Changes are eventually consistent, so a value read seconds after an update or rotation can still be the old one.

AWS Secrets Manager errors and how to fix them

"Access denied" when reading or creating a secret

The IAM user or role lacks the Secrets Manager or KMS permission, or a policy condition such as time or IP address is not met.

1. Check the identity's IAM policy for the action named in the error, such as secretsmanager:GetSecretValue.
2. For a customer managed key, confirm the identity can use that KMS key.
3. For temporary credentials, confirm they have not expired and that the underlying role has the permission.

A new or changed value does not show up yet

Secrets Manager is eventually consistent and caches data.

1. Wait briefly and read the secret again.
2. Design callers to tolerate a short delay after updates and rotation.

"Connection reset by peer"

AWS closed an idle or reused connection, which is normal occasionally.

1. Update the AWS SDK or CLI and keep default retries on.
2. Cache secret values on the client so the app opens fewer connections.
3. If it persists, check the AWS Health Dashboard and your VPC endpoint, proxy, firewall and DNS path.

"Cannot generate a data key with an asymmetric KMS key"

The secret was given an asymmetric KMS key.

1. Choose a symmetric encryption KMS key or aws/secretsmanager.
2. Create the secret again with that key.

The CLI cannot find a secret from a partial ARN

The secret name ends in a hyphen and six characters, which looks like a full ARN.

1. Pass the secret's name or its complete ARN to --secret-id.
2. Run aws secretsmanager list-secrets to copy the exact ARN.

"This secret is managed by an AWS service"

Another service, such as Amazon RDS, owns the secret.

1. Run describe-secret and read the OwningService field, or check the service prefix in the name.
2. Change the secret through that service instead.

AWS Secrets Manager future trends: managed external secrets and post-quantum TLS

The current AWS documentation lists several capabilities that cut down on custom Lambda code and hand more secret handling to AWS.

Feature	What it adds
Managed external secrets	Stores and rotates secrets held by Secrets Manager partner applications without a Lambda function
AWS Workload Credentials Provider	One way to consume secrets across Lambda, ECS, EKS and EC2
Post-quantum TLS	Supported on endpoints in all Regions except the China Regions
BatchGetSecretValue	Reads a group of secrets in one call, selected by a name list or a filter
AI coding agent retrieval	Listed by AWS as a supported way to get secret values

AWS Secrets Manager documentation: references and further reading

• What is AWS Secrets Manager? — Official user guide start page
• AWS Secrets Manager pricing — Current per-secret and per-call prices with examples
• AWS Secrets Manager FAQs — AWS answers on rotation, security and billing
• Rotation schedules — rate() and cron() syntax and rotation windows
• AWS Secrets Manager quotas — Every limit and request rate
• AWS Secrets Manager best practices — Key choice, caching, access control and monitoring
• Troubleshooting AWS Secrets Manager — Documented errors and fixes
• AWS CLI secretsmanager reference — Full syntax and sample output for each command

AWS Secrets Manager FAQ

What is AWS Secrets Manager?

AWS Secrets Manager is an AWS service for storing, retrieving and rotating secrets such as database credentials, API keys and OAuth tokens. It encrypts each value with AWS KMS, controls access with IAM, and lets applications fetch credentials at runtime instead of keeping them in source code.

What does AWS Secrets Manager do?

It keeps secrets encrypted in one place, returns them to authorised callers over TLS, rotates them on a schedule, replicates them across Regions and logs every access in CloudTrail. The main job is removing hard-coded passwords and long-lived credentials from code and configuration files.

How does AWS Secrets Manager work?

Each secret value is encrypted with a unique AES-256 data key that AWS KMS generates and protects. When an authorised caller requests the secret, Secrets Manager decrypts it and returns the current version. Rotation writes a new version, tests it, then promotes it to AWSCURRENT.

Is AWS Secrets Manager free?

No. As of October 2026 it costs $0.40 per secret per month plus $0.05 per 10,000 API calls. New AWS customers get up to $200 in Free Tier credits that can be spent on Secrets Manager, and the aws/secretsmanager encryption key itself has no charge.

How do I access AWS Secrets Manager?

Sign in to the AWS Management Console and open https://console.aws.amazon.com/secretsmanager/, or use the AWS CLI commands under aws secretsmanager, AWS Tools for Windows PowerShell, an AWS SDK or the HTTPS Query API. Your IAM identity needs Secrets Manager permissions for each action.

How do I use AWS Secrets Manager in my application?

Store the credential as a secret, give the application's IAM role secretsmanager:GetSecretValue on it, and replace the hard-coded value with an SDK call or caching library that fetches the secret at runtime. Lambda functions can use the AWS Parameters and Secrets Lambda Extension instead of an SDK.

Is AWS Secrets Manager global or regional?

It is regional. Each secret lives in one Region and its ARN contains that Region. You can replicate a secret to other Regions, where rotation in the primary updates every replica, or call another Region's endpoint to read a secret without replicating it.

Is AWS Secrets Manager set up per account?

Yes. Secrets belong to one AWS account and Region, and the 500,000-secret quota applies per Region per account. Another account can read a secret only if it is encrypted with a customer managed KMS key and a resource policy grants that account access.

What is the Azure equivalent of AWS Secrets Manager?

Azure Key Vault is Microsoft's equivalent. It stores tokens, passwords, certificates, API keys and other secrets, and also manages encryption keys and TLS certificates. Choose the store that belongs to the cloud where your workload runs.

What is the difference between AWS Secrets Manager and Parameter Store?

Secrets Manager rotates credentials automatically, replicates across Regions and charges $0.40 per secret a month. Parameter Store standard parameters cost nothing extra but never rotate. AWS recommends Parameter Store for configuration data and Secrets Manager for credentials, API keys and tokens.

How do I delete an AWS Secrets Manager secret immediately?

Run aws secretsmanager delete-secret --secret-id <name> --force-delete-without-recovery. The secret is deleted with no recovery window and cannot be restored. Remove any replicas first, because a primary secret with replicas cannot be deleted.

How often can AWS Secrets Manager rotate a secret?

As often as every four hours, and as rarely as every 999 days. You set the schedule with a rate() or cron() expression in UTC, plus an optional rotation window of at least one hour during which Secrets Manager performs the rotation.

Is AWS Secrets Manager worth it?

Use AWS Secrets Manager for any credential your AWS workloads use that should rotate or be audited, and keep plain configuration in Parameter Store standard parameters. At $0.40 per secret a month (October 2026), automatic rotation, CloudTrail auditing and Region replication cost far less than building them yourself, while Parameter Store covers non-secret settings at no extra charge.