Create and Update Secrets With AWS SDK v3 (Secrets Manager)

// create-secret.ts: create a Secrets Manager secret holding a JSON value, encrypted with your own KMS key.
// Usage: KMS_KEY_ID=alias/app-secrets npx tsx create-secret.ts
import { SecretsManagerClient, CreateSecretCommand } from "@aws-sdk/client-secrets-manager";

const client = new SecretsManagerClient({ region: process.env.AWS_REGION ?? "us-east-1" });

const value = {
  username: "billing_app",
  password: process.env.DB_PASSWORD ?? "change-me-before-use",
  host: "billing.cluster-abc123.us-east-1.rds.amazonaws.com",
  port: 5432,
};

const out = await client.send(new CreateSecretCommand({
  Name: "prod/billing/db", // letters, digits and /_+=.@- only; don't end it with a hyphen and six characters
  Description: "Billing service database login",
  SecretString: JSON.stringify(value), // up to 65,536 bytes
  KmsKeyId: process.env.KMS_KEY_ID, // omit to use the AWS managed key aws/secretsmanager
  Tags: [
    { Key: "app", Value: "billing" },
    { Key: "env", Value: "prod" },
  ],
}));

console.log(`Created ${out.Name}`);
console.log(`ARN:        ${out.ARN}`);
console.log(`Version ID: ${out.VersionId}`);

Created prod/billing/db
ARN:        arn:aws:secretsmanager:us-east-1:123456789012:secret:prod/billing/db-Xy9Kq2
Version ID: 7c4e2a90-1b3d-4f6a-9e8c-2d5b7a1f0c34

// secrets.ts: create-or-update, roll back and schedule deletion of Secrets Manager secrets with SDK v3.
import { randomUUID } from "node:crypto";
import {
  SecretsManagerClient,
  CreateSecretCommand,
  DeleteSecretCommand,
  ListSecretVersionIdsCommand,
  PutSecretValueCommand,
  ResourceExistsException,
  ResourceNotFoundException,
  UpdateSecretVersionStageCommand,
} from "@aws-sdk/client-secrets-manager";

export interface WriteResult {
  action: "created" | "updated";
  arn: string;
  versionId: string;
}

/**
 * Store a JSON value under `name`: a new version if the secret exists, otherwise a new secret.
 * Pass the same `token` when you retry the same logical write, so a retry can't add a second version.
 */
export async function upsertSecret(
  client: SecretsManagerClient,
  name: string,
  value: unknown,
  opts: { kmsKeyId?: string; token?: string } = {},
): Promise<WriteResult> {
  const SecretString = JSON.stringify(value);
  const ClientRequestToken = opts.token ?? randomUUID();
  try {
    const out = await client.send(new PutSecretValueCommand({ SecretId: name, SecretString, ClientRequestToken }));
    return { action: "updated", arn: out.ARN ?? "", versionId: out.VersionId ?? "" };
  } catch (err) {
    if (!(err instanceof ResourceNotFoundException)) throw err;
  }
  try {
    const out = await client.send(new CreateSecretCommand({ Name: name, SecretString, KmsKeyId: opts.kmsKeyId, ClientRequestToken }));
    return { action: "created", arn: out.ARN ?? "", versionId: out.VersionId ?? "" };
  } catch (err) {
    // Another process created the secret between our two calls: write the value as a new version instead.
    if (!(err instanceof ResourceExistsException)) throw err;
    const out = await client.send(new PutSecretValueCommand({ SecretId: name, SecretString, ClientRequestToken: randomUUID() }));
    return { action: "updated", arn: out.ARN ?? "", versionId: out.VersionId ?? "" };
  }
}

/** Version IDs that currently carry AWSCURRENT and AWSPREVIOUS. */
export async function currentAndPrevious(client: SecretsManagerClient, name: string): Promise<{ current?: string; previous?: string }> {
  const out = await client.send(new ListSecretVersionIdsCommand({ SecretId: name }));
  const find = (label: string) => out.Versions?.find((v) => v.VersionStages?.includes(label))?.VersionId;
  return { current: find("AWSCURRENT"), previous: find("AWSPREVIOUS") };
}

/** Point AWSCURRENT back at the AWSPREVIOUS version. Secrets Manager moves AWSPREVIOUS to the old current. */
export async function rollbackSecret(client: SecretsManagerClient, name: string): Promise<string> {
  const { current, previous } = await currentAndPrevious(client, name);
  if (!current || !previous) throw new Error(`${name} has no AWSPREVIOUS version to roll back to`);
  await client.send(new UpdateSecretVersionStageCommand({
    SecretId: name,
    VersionStage: "AWSCURRENT",
    MoveToVersionId: previous,
    RemoveFromVersionId: current,
  }));
  return previous;
}

/** Schedule deletion with a 7 to 30 day recovery window; RestoreSecret cancels it before the date. */
export async function scheduleDelete(client: SecretsManagerClient, name: string, days = 30): Promise<Date | undefined> {
  if (!Number.isInteger(days) || days < 7 || days > 30) throw new Error("recovery window must be 7 to 30 days");
  const out = await client.send(new DeleteSecretCommand({ SecretId: name, RecoveryWindowInDays: days }));
  return out.DeletionDate;
}

// use-secrets.ts: write a secret twice, show the version labels, roll back, then schedule deletion.
// Usage: npx tsx use-secrets.ts
import { SecretsManagerClient } from "@aws-sdk/client-secrets-manager";
import { currentAndPrevious, rollbackSecret, scheduleDelete, upsertSecret } from "./secrets.js";

const client = new SecretsManagerClient({ region: process.env.AWS_REGION ?? "us-east-1" });
const name = "dev/webhooks/stripe";

const first = await upsertSecret(client, name, { signingSecret: "whsec_old" });
console.log(`${first.action} ${name} -> version ${first.versionId}`);

const second = await upsertSecret(client, name, { signingSecret: "whsec_new" });
console.log(`${second.action} ${name} -> version ${second.versionId}`);
console.log("labels:", await currentAndPrevious(client, name));

const restored = await rollbackSecret(client, name);
console.log(`rolled back: AWSCURRENT is now ${restored}`);

const deletionDate = await scheduleDelete(client, name, 7);
console.log(`scheduled for deletion on ${deletionDate?.toISOString()}`);

created dev/webhooks/stripe -> version b217bdf1-3e1f-4f4c-80c0-accd9ccb5058
updated dev/webhooks/stripe -> version 6d2f419b-90c9-4671-acf9-4b4ee82c8dda
labels: {
  current: '6d2f419b-90c9-4671-acf9-4b4ee82c8dda',
  previous: 'b217bdf1-3e1f-4f4c-80c0-accd9ccb5058'
}
rolled back: AWSCURRENT is now b217bdf1-3e1f-4f4c-80c0-accd9ccb5058
scheduled for deletion on 2027-07-29T09:00:00.000Z

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "WriteAppSecrets",
      "Effect": "Allow",
      "Action": [
        "secretsmanager:CreateSecret",
        "secretsmanager:PutSecretValue",
        "secretsmanager:TagResource",
        "secretsmanager:ListSecretVersionIds",
        "secretsmanager:UpdateSecretVersionStage",
        "secretsmanager:DeleteSecret",
        "secretsmanager:RestoreSecret"
      ],
      "Resource": [
        "arn:aws:secretsmanager:us-east-1:123456789012:secret:prod/billing/*",
        "arn:aws:secretsmanager:us-east-1:123456789012:secret:dev/webhooks/*"
      ]
    },
    {
      "Sid": "UseSecretsKey",
      "Effect": "Allow",
      "Action": ["kms:GenerateDataKey", "kms:Decrypt"],
      "Resource": "arn:aws:kms:us-east-1:123456789012:key/1234abcd-12ab-34cd-56ef-1234567890ab"
    }
  ]
}