AWS.SecretsManager reference

BatchGetSecretValue

Source: src/AWS/SecretsManager/BatchGetSecretValue.ts

Runtime binding for secretsmanager:BatchGetSecretValue.

Bind this operation to a list of Secrets to get a callable that reads all of their current values in a single call — the batch counterpart of GetSecretValue. The bound secrets’ ARNs are injected as the SecretIdList and each secret is granted secretsmanager:GetSecretValue (BatchGetSecretValue authorizes per-secret through GetSecretValue). Provide the implementation with Effect.provide(AWS.SecretsManager.BatchGetSecretValueHttp).

BatchGetSecretValue: Reading Secret Values

// init — bind the operation to the secrets
const batchGet = yield* AWS.SecretsManager.BatchGetSecretValue([
  dbSecret,
  apiKeySecret,
]);

// runtime — one call, every current value
const result = yield* batchGet();
for (const entry of result.SecretValues ?? []) {
  console.log(entry.Name);
}

DescribeSecret

Source: src/AWS/SecretsManager/DescribeSecret.ts

Runtime binding for secretsmanager:DescribeSecret.

Bind this operation to a Secret to get a callable that reads the secret’s metadata (name, description, rotation config, version stages) without exposing its value. Provide the implementation with Effect.provide(AWS.SecretsManager.DescribeSecretHttp).

DescribeSecret: Inspecting Secrets

// init — bind the operation to the secret
const describeSecret = yield* AWS.SecretsManager.DescribeSecret(secret);

// runtime — metadata only, no secret value in the response
const info = yield* describeSecret();
const arn = info.ARN;
const description = info.Description;

GetRandomPassword

Source: src/AWS/SecretsManager/GetRandomPassword.ts

Runtime binding for secretsmanager:GetRandomPassword.

Account-level operation (no target secret): bind it with no arguments to get a callable that generates cryptographically strong random passwords — typically paired with PutSecretValue for rotation. Provide the implementation with Effect.provide(AWS.SecretsManager.GetRandomPasswordHttp).

GetRandomPassword: Generating Passwords

// init — account-level, no resource argument
const getRandomPassword = yield* AWS.SecretsManager.GetRandomPassword();
const putSecretValue = yield* AWS.SecretsManager.PutSecretValue(secret);

// runtime — generate, then rotate the secret to it
const generated = yield* getRandomPassword({
  PasswordLength: 32,
  ExcludePunctuation: true,
});
yield* putSecretValue({ SecretString: generated.RandomPassword });

GetSecretValue

Source: src/AWS/SecretsManager/GetSecretValue.ts

Runtime binding for secretsmanager:GetSecretValue.

Bind this operation to a Secret in the function’s init phase to get a callable that reads the current (or a specific) secret version — the secret ARN is injected automatically and secretsmanager:GetSecretValue is granted on the secret. Provide the implementation with Effect.provide(AWS.SecretsManager.GetSecretValueHttp).

Secret values are sensitive: SecretString / SecretBinary may be handed back wrapped in Redacted — unwrap with Redacted.value before use.

AWS lists secretsmanager:GetSecretValue as the required permission for retrieving the value; DescribeSecret is metadata-only and is not needed. If the secret uses a customer-managed KMS key, the caller additionally needs kms:Decrypt for that key. See the GetSecretValue API and Secrets Manager authorization reference.

GetSecretValue: Reading Secret Values

// init — bind the operation to the secret
const secret = yield* AWS.SecretsManager.Secret("DbPassword", {
  secretString: Redacted.make("initial-password"),
});
const getSecretValue = yield* AWS.SecretsManager.GetSecretValue(secret);

// runtime — reads the AWSCURRENT version
const result = yield* getSecretValue();
const value =
  typeof result.SecretString === "string"
    ? result.SecretString
    : Redacted.value(result.SecretString!);

ListSecrets

Source: src/AWS/SecretsManager/ListSecrets.ts

Runtime binding for secretsmanager:ListSecrets.

Account-level operation (no target secret): bind it with no arguments to get a callable that lists the account’s secrets (metadata only, never values). Provide the implementation with Effect.provide(AWS.SecretsManager.ListSecretsHttp).

ListSecrets: Listing Secrets

// init — account-level, no resource argument
const listSecrets = yield* AWS.SecretsManager.ListSecrets();

// runtime — filter server-side by name
const result = yield* listSecrets({
  Filters: [{ Key: "name", Values: ["my-app/"] }],
});
const names = (result.SecretList ?? []).map((entry) => entry.Name);

ListSecretVersionIds

Source: src/AWS/SecretsManager/ListSecretVersionIds.ts

Runtime binding for secretsmanager:ListSecretVersionIds.

Bind this operation to a Secret to get a callable that lists the secret’s version IDs and their staging labels (AWSCURRENT, AWSPENDING, AWSPREVIOUS) — useful for rotation functions and audit tooling. Provide the implementation with Effect.provide(AWS.SecretsManager.ListSecretVersionIdsHttp).

ListSecretVersionIds: Inspecting Secrets

// init — bind the operation to the secret
const listVersions = yield* AWS.SecretsManager.ListSecretVersionIds(secret);

// runtime — every version with its staging labels
const result = yield* listVersions({ IncludeDeprecated: true });
const current = (result.Versions ?? []).find((version) =>
  version.VersionStages?.includes("AWSCURRENT"),
);

PutSecretValue

Source: src/AWS/SecretsManager/PutSecretValue.ts

Runtime binding for secretsmanager:PutSecretValue.

Bind this operation to a Secret to get a callable that writes a new secret version (string or binary); the new version becomes AWSCURRENT. Provide the implementation with Effect.provide(AWS.SecretsManager.PutSecretValueHttp).

PutSecretValue: Writing Secret Values

Rotate a Secret’s Value

// init — bind the operation to the secret
const putSecretValue = yield* AWS.SecretsManager.PutSecretValue(secret);

// runtime — write a new version; the response carries its VersionId
const result = yield* putSecretValue({
  SecretString: newPassword,
});

Store a Binary Payload

yield* putSecretValue({
  SecretBinary: new TextEncoder().encode(JSON.stringify(credentials)),
});

RotateSecret

Source: src/AWS/SecretsManager/RotateSecret.ts

Runtime binding for secretsmanager:RotateSecret.

Bind this operation to a Secret to get a callable that triggers an immediate rotation using the secret’s configured rotation function (see onSecretRotation for wiring one up). Provide the implementation with Effect.provide(AWS.SecretsManager.RotateSecretHttp).

RotateSecret: Rotating Secrets

// init — bind the operation to the secret
const rotateSecret = yield* AWS.SecretsManager.RotateSecret(secret);

// runtime — kicks off the configured rotation function
const result = yield* rotateSecret();
const pendingVersionId = result.VersionId;

RotationEventSource

Source: src/AWS/SecretsManager/RotationEventSource.ts

Event source connecting a Secrets Manager Secret’s rotation to the hosting Lambda function.

The contract is a Binding.Service; the Lambda implementation layer is Lambda.SecretRotationEventSource — at deploy time it grants Secrets Manager permission to invoke the function, attaches the rotation-protocol IAM actions for the secret, and provisions the RotationSchedule; at runtime it narrows incoming invocations to rotation events for the bound secret. Consume it through the onSecretRotation helper.

RotationEventSource: Rotating Secrets

export default RotationFunction.make(
  { main: import.meta.url },
  Effect.gen(function* () {
    const secret = yield* SecretsManager.Secret("DbPassword", {
      secretString: Redacted.make("initial"),
    });
    const getValue = yield* SecretsManager.GetSecretValue(secret);
    const putValue = yield* SecretsManager.PutSecretValue(secret);
    const updateStage = yield* SecretsManager.UpdateSecretVersionStage(secret);
    const describe = yield* SecretsManager.DescribeSecret(secret);
    const randomPassword = yield* SecretsManager.GetRandomPassword();

    yield* SecretsManager.onSecretRotation(
      secret,
      { rotationRules: { automaticallyAfter: "30 days" } },
      (event) => rotate(event).pipe(Effect.orDie),
    );
  }).pipe(Effect.provide(Lambda.SecretRotationEventSource)),
);

RotationSchedule

Source: src/AWS/SecretsManager/RotationSchedule.ts

Configures automatic rotation on a Secrets Manager secret (RotateSecret with a rotation Lambda + rules; CancelRotateSecret on delete).

Usually created for you by onSecretRotation, which also wires the invoke permission and the runtime handler — reach for the resource directly only when the rotation function is managed outside the current stack.

RotationSchedule: Scheduling Rotation

Rotate Every 30 Days

const schedule = yield* RotationSchedule("DbSecretRotation", {
  secretId: secret.secretArn,
  rotationLambdaArn: rotationFunctionArn,
  rotationRules: { automaticallyAfter: "30 days" },
});

Cron Schedule with a Rotation Window

const schedule = yield* RotationSchedule("DbSecretRotation", {
  secretId: secret.secretArn,
  rotationLambdaArn: rotationFunctionArn,
  rotationRules: {
    scheduleExpression: "cron(0 8 1 * ? *)",
    window: "3 hours",
  },
});

Secret

Source: src/AWS/SecretsManager/Secret.ts

An AWS Secrets Manager secret.

Secret owns the lifecycle of the secret metadata and current value. It can store a caller-provided value or generate a password-backed JSON payload for downstream resources such as Aurora clusters and RDS proxies.

Secret: Creating Secrets

Static Secret String

const secret = yield* Secret("DbSecret", {
  secretString: Redacted.make(JSON.stringify({
    username: "app",
    password: "super-secret",
  })),
});

Generated Password Secret

const secret = yield* Secret("DbSecret", {
  generateSecretString: {
    secretStringTemplate: JSON.stringify({ username: "app" }),
    generateStringKey: "password",
    PasswordLength: 32,
  },
});

Secret: Resource Policies

const secret = yield* Secret("SharedSecret", {
  secretString: Redacted.make("shared-value"),
  resourcePolicy: {
    Version: "2012-10-17",
    Statement: [
      {
        Effect: "Allow",
        Principal: { AWS: `arn:aws:iam::${accountId}:root` },
        Action: ["secretsmanager:GetSecretValue"],
        Resource: "*",
      },
    ],
  },
});

UpdateSecretVersionStage

Source: src/AWS/SecretsManager/UpdateSecretVersionStage.ts

Runtime binding for secretsmanager:UpdateSecretVersionStage.

Bind this operation to a Secret to get a callable that moves a staging label between versions — the final finishSecret step of the rotation protocol, where AWSCURRENT is moved onto the new version. Provide the implementation with Effect.provide(AWS.SecretsManager.UpdateSecretVersionStageHttp).

UpdateSecretVersionStage: Rotating Secrets

// init — bind the operation to the secret
const updateStage = yield* AWS.SecretsManager.UpdateSecretVersionStage(secret);

// runtime — finishSecret: move AWSCURRENT onto the pending version
yield* updateStage({
  VersionStage: "AWSCURRENT",
  MoveToVersionId: pendingVersionId,
  RemoveFromVersionId: currentVersionId,
});