What Is AWS Secrets Manager? Rotation, IAM and App Access
AWS Secrets Manager stores and rotates API keys and credentials outside your source tree. How rotation, IAM and GetSecretValue work for backends, and how Encore declares secrets in code so values never land in the repo.
AWS Secrets Manager stores API keys, database passwords, webhook signing secrets and OAuth tokens outside application source. You create a secret, control GetSecretValue with IAM, and optionally schedule rotation so the value changes on a cadence you choose.
Hard-coding those values or checking a plain .env into git remains a common leak path. This guide covers rotation, IAM for app access, and how Encore declares secrets in code so values stay out of the repository.
AWS Secrets Manager at a glance
How Secrets Manager works
A secret is a named resource with one or more encrypted versions. The Secrets Manager user guide describes the model: applications replace hard-coded credentials with a runtime call (or with injection from the task definition) and retrieve the current value when they need it. Versions can carry staging labels such as AWSCURRENT and AWSPENDING during rotation.
You retrieve a value with GetSecretValue through the AWS SDK, the CLI, or a service integration. ECS can map a secret ARN into a container environment variable at task start. Lambda and other compute options usually call the SDK (often with a short-lived cache) so each invoke does not pay a cold Secrets Manager round trip.
List pricing is $0.40 per secret per month plus $0.05 per 10,000 API calls, with no charge for secrets marked for deletion. Grouping related keys into one JSON secret reduces the per-secret bill, at the cost of coarser access control if every consumer needs the whole blob.
Rotation
Automatic rotation replaces a long-lived credential with a new version on a schedule. For database and many non-database secrets, Secrets Manager invokes a Lambda rotation function that creates a pending version, updates the backing system when required, tests it, then promotes it to AWSCURRENT.
The important application detail: consumers that read the secret once at process start keep the previous value until new processes start. ECS tasks that take secrets from the task definition behave the same way, which is why a rotation often needs a new deployment. Runtime readers that call GetSecretValue on a refresh interval pick up the new version without a redeploy, and must tolerate a brief window where both versions can be valid.
Managed rotation for some AWS-integrated credentials follows product-specific paths, and for application API keys you own, plan for the cache and restart behavior before you turn rotation on.
IAM and application access
Access is controlled entirely by IAM: an identity that needs the plaintext calls secretsmanager:GetSecretValue (and often DescribeSecret) on the secret ARN. If the secret is encrypted with a customer managed key, that identity also needs kms:Decrypt on the key. The authentication and access guide covers identity-based policies, resource policies and permission boundaries.
For ECS Fargate, the task execution role needs GetSecretValue when secrets are injected through the task definition, and the task role needs it when the application calls the SDK at runtime. Scope each statement to the secret ARNs that service actually uses. Broad secretsmanager:* on * turns one compromised task into a vault dump.
CloudTrail records Secrets Manager API calls as management events, which is how you audit who retrieved or changed a secret after the fact.
How Encore uses Secrets Manager
Each named secret in Encore is infrastructure from code, and the platform provisions and deploys into your own AWS or GCP account. You declare a secret by name in application code. Values are set through the CLI or the dashboard, encrypted in the Encore platform, and on AWS replicated into AWS Secrets Manager and injected at runtime. Encore secret values are not stored in the repo, so AI coding agents working in it cannot read or leak them.
On deploy, Encore provisions an IAM role for the service, as described in the AWS infrastructure docs. A missing secret value fails the deploy for cloud environments before the release goes live.
Set up the app
Run in your terminal to get started locally.
Declare the secret next to the code that uses it:
// billing/encore.service.ts
import { Service } from "encore.dev/service";
export default new Service("billing");
Resolve the secret inside the handler that needs it:
// billing/checkout.ts
import { api } from "encore.dev/api";
import { secret } from "encore.dev/config";
const stripeSecretKey = secret("StripeSecretKey");
export const charge = api(
{ expose: true, method: "POST", path: "/charge" },
async ({ amount }: { amount: number }): Promise<{ ok: boolean }> => {
const key = stripeSecretKey();
// call Stripe with key; value never appears in git
void key;
void amount;
return { ok: true };
},
);
encore secret set --type <types> <name> writes the value for environment types such as prod, dev, preview and local (or --env for one environment). The TypeScript secrets docs and Go secrets docs cover the APIs. Only the secret name appears in source; the value stays in the vault and, on AWS, in Secrets Manager.
An AI coding agent can add a secret("…") call or a secrets struct field in the same change as the integration code, run the handler under encore run after a human sets a local value, and never see production credentials in the repository diff.
Best fit: Teams who want Secrets Manager in their own AWS account, with secret names declared in application code, values kept out of git, and an IAM role provisioned for each service.
Good to know
- Rotation without a restart plan leaves running tasks on the old value.
- One JSON secret for many keys cheapens the per-secret fee and widens blast radius if every consumer shares it.
- Prefer task roles scoped to named ARNs over shared execution roles that can read every secret in the account.
- For the ECS task definition wiring path, see the companion how-to AWS Secrets Manager with ECS Fargate.
Related guides
Frequently asked questions
What is AWS Secrets Manager used for?
AWS Secrets Manager stores API keys, database passwords, OAuth tokens and similar credentials outside application source code. Applications retrieve values at runtime with GetSecretValue, and you can schedule automatic rotation so long-lived secrets become short-lived ones.
How does Secrets Manager rotation work?
For many secrets, Secrets Manager runs a Lambda rotation function on a schedule. The function creates a new credential version, updates the backing system when needed, and moves the AWSCURRENT staging label. Applications that only read the secret at process start keep the old value until they restart or redeploy.
How do I give an ECS or Lambda app access to a secret?
Attach an IAM policy that allows secretsmanager:GetSecretValue on that secret's ARN to the task role or execution role that needs it, plus kms:Decrypt if the secret uses a customer managed KMS key. Prefer resource-scoped policies over account-wide secretsmanager:*.
How do I declare an application secret with Encore without putting the value in git?
With Encore, declare the secret in code (a secrets struct field in Go, or secret("Name") in TypeScript), then set the value with encore secret set --type prod Name. The value is not stored in the repository. On AWS, Encore replicates it into Secrets Manager and injects it at runtime, and Encore provisions an IAM role for the service.
Deploy to your cloud on AWS and Google Cloud
without managing infrastructure
Encore lets developers and agents define application infrastructure directly in code, then automatically provisions it from local development to production in your AWS or GCP account.
