Key takeaways
- AWS Secrets Manager never rotates secrets itself; an attached Lambda runs four steps (create, set, test, finish) and shifts the AWSCURRENT and AWSPREVIOUS stage labels.
- Use AWS managed rotation templates for RDS, Redshift, and DocumentDB; for unsupported SaaS keys like Stripe or GitHub, you must write your own rotation Lambda.
- The test step is your outage guard: it validates the new credential before the finish step irreversibly revokes the old one.
- GCP Secret Manager has no rotation Lambdas; you get a schedule and a Pub/Sub notification, and the rotation logic is your code end to end.
- Match rotation cadence to blast radius: 90 days for low-risk internal creds, 30 days or less for keys touching production data or money.
AWS secret manager rotation works by attaching a Lambda function to a secret and scheduling it to swap credentials on a fixed cadence, so humans stop being the transport layer. This guide covers when to use a built-in rotation template, how to write a custom Lambda for secrets like Stripe API keys that AWS doesn't natively support, and how GCP's rotation model differs.
What does AWS Secrets Manager rotation actually do when you enable it?
Enabling rotation on a secret tells Secrets Manager to invoke a rotation Lambda on the schedule you set. The Lambda creates a new credential, stores it as a new version of the secret, updates the consuming service, and re-labels the stages. Secrets Manager never rotates anything itself; the Lambda does all the work, which is why the template you pick (or write) matters. AWS documents the full rotation strategy and managed templates for RDS, Redshift, and DocumentDB.
The four rotation steps the Lambda runs
Per AWS's design, the Lambda runs four steps: create a new credential, wait for any propagation, update the secret version, then finish and verify. Stages move from AWSCURRENT to AWSPREVIOUS as the new version takes over. If a step fails, the old credential stays live.
What AWSCURRENT and AWSPREVIOUS mean for your consumers
Anything reading the secret by stage label gets the new value on its next fetch, with no redeploy. Anything that cached the old value at startup keeps working until it re-reads, because AWSPREVIOUS still resolves. That grace window is what makes rotation survivable, and it is also why tracking expiry and ownership across your inventory matters as much as the rotation itself.
When should you use a built-in rotation template versus write your own rotation Lambda?
Decision criteria: provider support, blast radius, and team capacity
Start with provider support. AWS ships managed rotation templates for RDS, Redshift, and DocumentDB, plus a short list of SaaS providers. If your secret is one of those, use the template and skip the Lambda entirely. If not, you are writing one.
Then weigh blast radius against team capacity. A template rotates a database user password: one principal, one secret, well-understood failure modes. A custom Lambda rotating a Stripe or GitHub key touches every service holding that key, and a bug can lock out production mid-deploy. If nobody on your team can own a Lambda on call, a template or a manual schedule with a tracking layer beats a half-maintained script.
| Situation | Use a template | Write a custom Lambda |
|---|---|---|
| RDS/Redshift/DocumentDB user | Yes | No |
| Supported SaaS provider | Yes | No |
| Unsupported SaaS key | No | Only if API supports it and someone owns it |
| Shared key across many services | No | Risky; prefer short-lived creds |
Secrets that look supported but aren't
A GitHub PAT stored in Secrets Manager has no AWS template. Neither does a Stripe restricted key. For those, the realistic options are a custom Lambda against the provider's API, or keeping a 30/60/90 day manual rotation policy with explicit owners and expiry dates tracked outside the vault, which is where credential lifecycle monitoring like KeyGuardRail fits. We cover the trade-offs in our guide to alternatives to manual credential rotation tracking.
How do you set up a rotation Lambda for a secret AWS doesn't natively support?
AWS ships rotation templates for RDS, DocumentDB, and Redshift, but a Stripe key or GitHub PAT is on you. The pattern is still the same four steps AWS defines for every rotation Lambda: create, set, test, and finish. See the AWS Secrets Manager documentation for the exact contract.
Step 1: Create the secret and tag an owner
Store the current Stripe key in Secrets Manager with a SecretRotation:Enabled tag and an Owner tag like payments-platform. Metadata only in the name field is fine, but the secret value must be the real key, since your Lambda reads it to build the API call.
Step 2: Write the four-step rotation Lambda
The long paragraph: The create step calls Stripe's API to issue a new restricted key and stages it as AWSPENDING without touching the live value. The set step promotes AWSPENDING to AWSCURRENT, which is where every consumer of that secret picks up the new key on next read. The test step validates AWSCURRENT with a low-risk call, such as listing charges with a limit of one, and aborts rotation if it fails, leaving the old key usable. The finish step deletes AWSPENDING, revokes the old key through Stripe, and closes out the version chain.
Skipping the test step is how a bad key becomes an outage, because finish is irreversible once the old credential is revoked. The full lifecycle of an API key, from issuance to revocation, is exactly what this state machine encodes, and the same shape works for GitHub PATs or any SaaS provider with a create-and-revoke API. If you want the broader picture beyond AWS, this guide to API key lifecycle management covers ownership and expiry tracking across providers.
Step 3: Configure the rotation schedule and IAM role
Attach the Lambda with rotateSecret and a schedule expression like rate(90 days). The Lambda's IAM role needs secretsmanager:GetSecretValue, PutSecretValue, UpdateSecretVersionStage, and DescribeSecret on this secret only, plus whatever permissions the provider call needs.
Worked example: rotating a Stripe API key
A payments team runs this against their Stripe restricted key on a 90-day schedule. The Lambda creates the replacement, promotes it, verifies it with a test charge lookup, then revokes the old key. Ownership is recorded in the tag, so when the rotation fails at 2am, the on-call knows who to page.
What are the most common reasons rotation Lambdas fail?
Permission and networking failures
The most common failure is a missing iam:PassRole permission, which stops the rotation Lambda from assuming the execution role at all. The rotation fails before any provider API call happens. If your Lambda sits in a VPC, missing NAT routes or security group rules can block the call to Stripe or GitHub, and the timeout shows up as a generic Lambda error rather than a clear network message.
Silent test-step failures and stale caches
The second cluster of failures happens after the new secret value is created. The test step (testSecret) can fail without alerting anyone, leaving the secret marked as rotating while consumers keep the old value. Caches make this worse: a service that read the secret at startup keeps serving it until restart, so rotation "succeeds" in Secrets Manager but nothing downstream picks it up. Tracking which services consume which credentials, and when they last refreshed, closes that gap; we cover the multi-cloud version of this problem in how to manage API keys across multiple cloud providers.
How does GCP Secret Manager rotation differ from AWS Secrets Manager rotation?
GCP: scheduler plus your own rotation code
GCP Secret Manager has no rotation Lambdas. You get two things: a rotation schedule on the secret and a rotation notification published to a Pub/Sub topic. The actual credential change is yours to build, typically a Cloud Scheduler job or that notification triggering a Cloud Function or Workflows execution that calls the provider's API, writes the new value, and updates consumers.
That is the core difference. AWS gives you managed templates for RDS, Redshift, and DocumentDB plus a Lambda frame for everything else. GCP gives you a schedule and a message, and the rotation logic is your code end to end. For SaaS keys like Stripe or GitHub, both platforms stop at the same line: neither rotates them natively, so ownership and deadline tracking live outside the vault. Assigning an owner per key is the first step (https://keyguardrail.com/blog/how-to-assign-owners-to-api-keys).
AWS vs GCP rotation at a glance
| Mechanic | AWS Secrets Manager | GCP Secret Manager |
|---|---|---|
| Managed rotation for native DBs | Yes, via templates | No |
| Rotation code runtime | Lambda (yours or template) | Your Cloud Function/Workflows |
| Schedule source | Secrets Manager schedule | Secret schedule + Cloud Scheduler |
| Notification of due rotation | EventBridge | Pub/Sub message |
| SaaS key rotation | Not built in | Not built in |
Cost differs too. AWS bills each rotation as a Lambda invocation plus API calls on top of per-secret pricing (AWS Secrets Manager pricing), so a 30/60/90 day rotation policy across hundreds of secrets shows up on the invoice.
What AWS Secrets Manager rotation best practices prevent outages during rotation?
Use AWSPREVIOUS as your rollback path
Secrets Manager keeps the previous version in the AWSPREVIOUS staging label for at least the waiting window you set, typically 24 hours. Treat that as your rollback path: if a rotated credential breaks a dependent service, re-point AWSCURRENT to AWSPREVIOUS instead of debugging under pressure. Run your rotation Lambda's createSecret and testSecret steps against a real dependency, not a staging stand-in, so the test step catches what your integration actually sees. Schedule rotations outside peak traffic windows; a failed rotation at 2 a.m. is an incident, the same failure at 10 a.m. is a ticket.
Monitor rotation success as a first-class signal
A rotation that fails silently leaves you with an expired credential and no audit trail of who knew. Subscribe to Secrets Manager events through EventBridge and alarm on rotation failures in CloudWatch, so a stuck AWSPENDING label pages someone before the next successful auth does. Keep humans out of the transport path: the Lambda rotates the secret value, your services read AWSCURRENT, and nobody copies keys between systems by hand.
How often should you schedule secret rotation in AWS?
Use the 30/60/90 day policy most platform teams already run: 90 days for low-blast-radius internal creds, 60 for shared service accounts, 30 for anything touching production data or money. Keys that can move funds or push to all repos deserve 30 days or less.
Matching cadence to blast radius
Rank each secret by what an attacker does with it, not by how hard rotation is. A Stripe key that can issue refunds and a GitHub PAT with org admin scope are both 30-day candidates, regardless of provider.
Where the provider supports short-lived credentials, prefer them over scheduled rotation entirely. STS sessions and OAuth tokens expire on their own, so a missed rotation window stops being an incident. Note the limits elsewhere: Google Cloud Secret Manager documents that it does not rotate secret values itself, you schedule the change externally (Google Cloud Secret Manager docs).
Rotation solves AWS secrets, but who tracks the rest of your credential inventory?
The gap between rotation and lifecycle ownership
Rotation Lambdas only cover secrets inside Secrets Manager. Your Stripe keys, GitHub tokens, and the credentials sitting in Postman collections or a second vault like Infisical or HashiCorp Vault have no expiry tracking, no owner, and no rotation deadline. That is the sprawl problem: the vault solved storage, not coordination.
Where KeyGuardRail fits, and where it doesn't
KeyGuardRail monitors credential lifecycle across AWS Secrets Manager and SaaS providers like Stripe and GitHub, tracking who owns each key, when it expires, and when the next rotation is due. It reads metadata only, never secret values, so there is no custody question and no change to your existing vault setup. Self-serve signup, with a Starter tier for small teams.
The honest limitation: it does not rotate anything. You still write and run the Lambdas from the sections above. KeyGuardRail tells you what expires and who owns it; the rotation itself stays in your hands.
FAQ
Can AWS Secrets Manager rotate a static API key from a provider that has no rotation API?
No. Rotation requires the Lambda to create a new credential and revoke the old one through the provider's API. If the provider offers no create-and-revoke endpoints, there is nothing for the Lambda to call. Your fallback is a manual 30/60/90 day policy with tracked owners and expiry dates outside the vault.
How much does a rotation Lambda cost to run each month?
The Lambda invocation itself is pennies; a 90-day schedule is four runs a month. The real line items are Secrets Manager pricing: $0.40 per secret per month plus $0.05 per 10,000 API calls, per AWS's published rates. Rotating hundreds of secrets on short cadences makes the API call charges the visible part of the bill.
Does rotating a secret in Secrets Manager immediately invalidate the old value?
No. The old version keeps the AWSPREVIOUS stage label and still resolves for consumers that cached it, typically for at least the waiting window you configure. Revocation only happens if your Lambda explicitly invalidates the old credential at the provider, which is why the finish step is irreversible once it runs.
Can I rotate secrets in Secrets Manager from Terraform or CloudFormation?
Yes. Terraform's aws_secretsmanager_secret_rotation resource and CloudFormation's AWS::SecretsManager::RotationSchedule both attach a rotation Lambda and schedule to a secret. They configure the trigger, not the logic: you still supply the Lambda itself, either a managed template for supported databases or your own code for SaaS keys.
What's the difference between secret rotation and secret versioning in AWS?
Versioning is the storage mechanic: each change to a secret creates a version labeled AWSCURRENT or AWSPREVIOUS. Rotation is the workflow that produces a new version: a Lambda creates a credential, tests it, and shifts the stage labels. You can version secrets by hand forever; rotation automates producing and promoting those versions.