Skip to main content

USE AWS SECRETS MANAGER

Prerequisites

  • swamp auth login completed, or SWAMP_API_KEY set with vault:* 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-sm

Create 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-password

Each 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-token and oauth-resolved-admins into its datastore and deletes them from Secrets Manager, when its credentials allow secretsmanager:DeleteSecret. Other oauth-* 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-id and oauth-client-secret stay 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:

  1. 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'
  2. 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.

  3. Delete a leftover oauth-resolved-admins by 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=infra

Only 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=quarterly

To remove a label:

swamp vault annotate my-aws-vault api-key --remove-label rotation

To remove all annotations from a secret:

swamp vault annotate my-aws-vault api-key --clear

Inspect Metadata

swamp vault inspect my-aws-vault api-key
INF 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.