USE AWS SECRETS MANAGER
Prerequisites
swamp auth logincompleted, orSWAMP_API_KEYset withvault:*scope- AWS credentials available via the default credential chain (environment
variables,
~/.aws/credentials, an SSO profile in~/.aws/config, or an IAM role) — refer to Authenticate to AWS with SSO for the SSO sequence - IAM permissions:
secretsmanager:GetSecretValue,secretsmanager:PutSecretValue,secretsmanager:CreateSecret,secretsmanager:ListSecrets
Pull the Extension
swamp extension pull @swamp/aws-smCreate the Vault
swamp vault create @swamp/aws-sm my-aws-vault \
--config '{"region": "us-east-1"}'INF vault·create Created vault: "my-aws-vault" ("AWS Secrets Manager")Store Secrets
swamp vault put my-aws-vault api-key
swamp vault put my-aws-vault db-passwordEach command prompts for the value with echo suppressed. To pipe from a secrets
manager or environment variable instead, use
echo "$SECRET" | swamp vault put my-aws-vault <key>.
Secret keys map directly to AWS Secrets Manager secret names, including
path-style names such as myapp/production/db-password.
The vault's config is only region and profile, and listing it lists every
secret in the account and region. Two Swamp vaults on one account and region are
the same store: a key put through one is read, listed and overwritten through
the other.
Share an Account with swamp serve
swamp serve does not store its OAuth values in Secrets Manager. It keeps them
in its datastore; see
where token secrets are stored.
Secrets named oauth-* can still exist in the account, left by an older serve
or seeded by hand. When the Secrets Manager vault is the repository's default
vault (or its first vault, with no default set), an instance started without a
supplied OAuth client secret on an empty datastore adopts that client:
- It copies
oauth-client-id,oauth-client-secret,oauth-bootstrap-access-tokenandoauth-resolved-adminsinto its datastore and deletes them from Secrets Manager, when its credentials allowsecretsmanager:DeleteSecret. Otheroauth-*secrets stay. - A deleted name cannot be reused until its recovery window, 30 days by default, has passed.
- The next instance started the same way finds no client and registers a new one.
- With
--keep-oauth-client-in-vault,oauth-client-idandoauth-client-secretstay in Secrets Manager, and every such instance shares that client.
An instance given its own client secret (--oauth-client-secret-file,
SWAMP_OAUTH_CLIENT_SECRET_FILE or SWAMP_OAUTH_CLIENT_SECRET) leaves flat
oauth-* secrets alone, neither moving nor reading them.
To keep instances that share an account apart:
Before starting a new instance, check the account for
oauth-*secrets:aws secretsmanager list-secrets --region us-east-1 \ --filters Key=name,Values=oauth- --query 'SecretList[].Name'
Do not seed flat
oauth-*names in a shared account. Give each instance its own client instead; see Recreate an instance without registering a new client.Delete a leftover
oauth-resolved-adminsby hand. An instance that once ran with a supplied client secret and later starts without one can leave it behind, and another instance can adopt it.
Annotate Secrets (Optional)
If the provider version supports annotations, attach provenance metadata to stored secrets.
swamp vault annotate my-aws-vault api-key \
--url https://console.aws.amazon.com/iam/home#/users/deploy \
--notes "Prod deploy key, rotated quarterly" \
--label env=prod --label team=infraOnly the fields you specify are updated. To add a label without changing the URL or notes:
swamp vault annotate my-aws-vault api-key --label rotation=quarterlyTo remove a label:
swamp vault annotate my-aws-vault api-key --remove-label rotationTo remove all annotations from a secret:
swamp vault annotate my-aws-vault api-key --clearInspect Metadata
swamp vault inspect my-aws-vault api-keyINF vault·inspect Metadata for "api-key" in vault "my-aws-vault":
INF vault·inspect size: 40 chars (40 bytes)
INF vault·inspect url: "https://console.aws.amazon.com/iam/home#/users/deploy"
INF vault·inspect notes: "Prod deploy key, rotated quarterly"
INF vault·inspect label: "env"="prod"
INF vault·inspect label: "team"="infra"
INF vault·inspect updated: "2026-05-23T02:04:58.668Z"
INF vault·inspect refresh-hook: (none)Use --json for structured output.
Reference Secrets in Behaviors
globalArguments:
api_key: "${{ vault.get('my-aws-vault', 'api-key') }}"See the Vaults reference for CEL integration, environment variable mounting, and the full CLI command reference.