# Secret

Creates a new secret in AWS SecretsManager.

Extends: Construct › Resource › Secret
Implements: IResource, ISecret, IEnvironmentAware, ISecretRef, IConstruct, IDependable
Superclass of: DatabaseSecret, DatabaseSecret, DatabaseSecret

- CloudFormation: [`AWS::SecretsManager::Secret`](https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-resource-secretsmanager-secret.html)
- L1 type: [`CfnSecret`](/cdk/api/v2/docs/aws-cdk-lib.aws_secretsmanager.CfnSecret.html)
- Source: [`aws-secretsmanager/lib/secret.ts`](https://github.com/aws/aws-cdk/blob/v2.274.0/packages/aws-cdk-lib/aws-secretsmanager/lib/secret.ts#L540)
- Type last changed: v2.234.0 · 8 Jan 2026

## Example

```ts
const user = new iam.User(this, 'User');
const accessKey = new iam.AccessKey(this, 'AccessKey', { user });
declare const stack: Stack;

new secretsmanager.Secret(this, 'Secret', {
  secretObjectValue: {
    username: SecretValue.unsafePlainText(user.userName),
    database: SecretValue.unsafePlainText('foo'),
    password: accessKey.secretAccessKey,
  },
})
```

## Initializer

```ts
new Secret(scope: Construct, id: string, props?: SecretProps)
```

## Construct Props

- `description`: string = No description. — An optional, human-friendly description of the secret.

- `encryptionKey`: [IKey](/cdk/api/v2/docs/aws-cdk-lib.aws_kms.IKey.html) = A default KMS key for the account and region is used. — The customer-managed encryption key to use for encrypting the secret value.

  **Default:** A default KMS key for the account and region is used.

- `generateSecretString`: [SecretStringGenerator](/cdk/api/v2/docs/aws-cdk-lib.aws_secretsmanager.SecretStringGenerator.html) = 32 characters with upper-case letters, lower-case letters, punctuation and numbers (at least one from each category), per the default values of ``SecretStringGenerator``. — Configuration for how to generate a secret value.

  Only one of `secretString` and `generateSecretString` can be provided.

  **Default:** 32 characters with upper-case letters, lower-case letters, punctuation and numbers (at least one from each category), per the default values of ``SecretStringGenerator``.

- `removalPolicy`: [RemovalPolicy](/cdk/api/v2/docs/aws-cdk-lib.RemovalPolicy.html) = Not set. — Policy to apply when the secret is removed from this stack.

- `replicaRegions`: [ReplicaRegion](/cdk/api/v2/docs/aws-cdk-lib.aws_secretsmanager.ReplicaRegion.html)[] = Secret is not replicated — A list of regions where to replicate this secret.

- `secretName`: string = A name is generated by CloudFormation. — A name for the secret.

  Note that deleting secrets from SecretsManager does not happen immediately, but after a 7 to
  30 days blackout period. During that period, it is not possible to create another secret that shares the same name.

  **Default:** A name is generated by CloudFormation.

- `secretObjectValue`: { [key: string]: [SecretValue](/cdk/api/v2/docs/aws-cdk-lib.SecretValue.html) } = SecretsManager generates a new secret value. — Initial value for a JSON secret.

  **NOTE:** *It is **highly** encouraged to leave this field undefined and allow SecretsManager to create the secret value.
  The secret object -- if provided -- will be included in the output of the cdk as part of synthesis,
  and will appear in the CloudFormation template in the console. This can be secure(-ish) if that value is merely reference to
  another resource (or one of its attributes), but if the value is a plaintext string, it will be visible to anyone with access
  to the CloudFormation template (via the AWS Console, SDKs, or CLI).

  Specifies a JSON object that you want to encrypt and store in this new version of the secret.
  To specify a simple string value instead, use `SecretProps.secretStringValue`

  Only one of `secretStringBeta1`, `secretStringValue`, 'secretObjectValue', and `generateSecretString` can be provided.

  **Default:** SecretsManager generates a new secret value.

  ```ts
  declare const user: iam.User;
  declare const accessKey: iam.AccessKey;
  declare const stack: Stack;
  new secretsmanager.Secret(stack, 'JSONSecret', {
    secretObjectValue: {
      username: SecretValue.unsafePlainText(user.userName), // intrinsic reference, not exposed as plaintext
      database: SecretValue.unsafePlainText('foo'), // rendered as plain text, but not a secret
      password: accessKey.secretAccessKey, // SecretValue
    },
  });
  ```

- `secretStringBeta1`: [SecretStringValueBeta1](/cdk/api/v2/docs/aws-cdk-lib.aws_secretsmanager.SecretStringValueBeta1.html) = SecretsManager generates a new secret value. — Use `secretStringValue` instead.

  **NOTE:** *It is **highly** encouraged to leave this field undefined and allow SecretsManager to create the secret value.
  The secret string -- if provided -- will be included in the output of the cdk as part of synthesis,
  and will appear in the CloudFormation template in the console. This can be secure(-ish) if that value is merely reference to
  another resource (or one of its attributes), but if the value is a plaintext string, it will be visible to anyone with access
  to the CloudFormation template (via the AWS Console, SDKs, or CLI).

  Specifies text data that you want to encrypt and store in this new version of the secret.
  May be a simple string value, or a string representation of a JSON structure.

  Only one of `secretStringBeta1`, `secretStringValue`, and `generateSecretString` can be provided.

  **Default:** SecretsManager generates a new secret value.

- `secretStringValue`: [SecretValue](/cdk/api/v2/docs/aws-cdk-lib.SecretValue.html) = SecretsManager generates a new secret value. — Initial value for the secret.

  **NOTE:** *It is **highly** encouraged to leave this field undefined and allow SecretsManager to create the secret value.
  The secret string -- if provided -- will be included in the output of the cdk as part of synthesis,
  and will appear in the CloudFormation template in the console. This can be secure(-ish) if that value is merely reference to
  another resource (or one of its attributes), but if the value is a plaintext string, it will be visible to anyone with access
  to the CloudFormation template (via the AWS Console, SDKs, or CLI).

  Specifies text data that you want to encrypt and store in this new version of the secret.
  May be a simple string value. To provide a string representation of JSON structure, use `SecretProps.secretObjectValue` instead.

  Only one of `secretStringBeta1`, `secretStringValue`, 'secretObjectValue', and `generateSecretString` can be provided.

  **Default:** SecretsManager generates a new secret value.

## Properties

- `encryptionKey`: [IKey](/cdk/api/v2/docs/aws-cdk-lib.aws_kms.IKey.html) — The customer-managed encryption key that is used to encrypt this secret, if any.

  When not specified, the default
  KMS key for the account and region is being used.

- `env`: [ResourceEnvironment](/cdk/api/v2/docs/aws-cdk-lib.interfaces.ResourceEnvironment.html) (required) — The environment this resource belongs to.

  For resources that are created and managed in a Stack (those created by
  creating new class instances like `new Role()`, `new Bucket()`, etc.), this
  is always the same as the environment of the stack they belong to.

  For referenced resources (those obtained from referencing methods like
  `Role.fromRoleArn()`, `Bucket.fromBucketName()`, etc.), they might be
  different than the stack they were imported into.

- `excludeCharacters`: string — The string of the characters that are excluded in this secret when it is generated.

- `node`: [Node](/cdk/api/v2/docs/constructs.Node.html) (required) — The tree node.

- `PROPERTY_INJECTION_ID`: string (required) (static) — Uniquely identifies this class.

- `secretArn`: string (required) — The ARN of the secret in AWS Secrets Manager.

  Will return the full ARN if available, otherwise a partial arn.
  For secrets imported by the deprecated `fromSecretName`, it will return the `secretName`.

- `secretFullArn`: string — The full ARN of the secret in AWS Secrets Manager, which is the ARN including the Secrets Manager-supplied 6-character suffix.

  This is equal to `secretArn` in most cases, but is undefined when a full ARN is not available (e.g., secrets imported by name).

- `secretName`: string (required) — The name of the secret.

  For "owned" secrets, this will be the full resource name (secret name + suffix), unless the
  '@aws-cdk/aws-secretsmanager:parseOwnedSecretName' feature flag is set.

- `secretRef`: [SecretReference](/cdk/api/v2/docs/aws-cdk-lib.interfaces.aws_secretsmanager.SecretReference.html) (required) — A reference to a Secret resource.

- `secretValue`: [SecretValue](/cdk/api/v2/docs/aws-cdk-lib.SecretValue.html) (required) — Retrieve the value of the stored secret as a `SecretValue`.

- `stack`: [Stack](/cdk/api/v2/docs/aws-cdk-lib.Stack.html) (required) — The stack in which this resource is defined.

## Methods

- `addReplicaRegion(region: string, encryptionKey?: IKeyRef): void` — Adds a replica region for the secret.

  **Parameters**

  - `region` — The name of the region.
  - `encryptionKey` — The customer-managed encryption key to use for encrypting the secret value.

- `addRotationSchedule(id: string, options: RotationScheduleOptions): RotationSchedule` — Adds a rotation schedule to the secret.

- `addToResourcePolicy(statement: PolicyStatement): AddToResourcePolicyResult` — Adds a statement to the IAM resource policy associated with this secret.

  If this secret was created in this stack, a resource policy will be
  automatically created upon the first call to `addToResourcePolicy`. If
  the secret is imported, then this is a no-op.

- `applyCrossStackReferenceStrength(strength: ReferenceStrength): void` — Override the cross-stack reference strength for this resource.

  When set, any cross-stack reference to this resource will use the specified
  mechanism instead of the global default determined by the
  `@aws-cdk/core:defaultCrossStackReferences` context key. This is useful for
  selectively weakening specific references to avoid the "deadly embrace" problem
  without changing the app-wide default.

  **Parameters**

  - `strength` — - The reference strength to use for this resource.

- `applyRemovalPolicy(policy: RemovalPolicy): void` — Apply the given removal policy to this resource.

  The Removal Policy controls what happens to this resource when it stops
  being managed by CloudFormation, either because you've removed it from the
  CDK application or because you've made a change that requires the resource
  to be replaced.

  The resource can be deleted (`RemovalPolicy.DESTROY`), or left in your AWS
  account for data recovery and cleanup later (`RemovalPolicy.RETAIN`).

- `attach(target: ISecretAttachmentTarget): ISecret` — Attach a target to this secret.

  **Parameters**

  - `target` — The target to attach.

  **Returns:** An attached secret

- `cfnDynamicReferenceKey(options?: SecretsManagerSecretOptions): string` — Returns a key which can be used within an AWS CloudFormation dynamic reference to dynamically load this secret from AWS Secrets Manager.

  **Parameters**

  - `options` — Options.

- `denyAccountRootDelete(): void` — Denies the `DeleteSecret` action to all principals within the current account.

- `fromSecretAttributes(scope: Construct, id: string, attrs: SecretAttributes): ISecret` (static) — Import an existing secret into the Stack.

  **Parameters**

  - `scope` — the scope of the import.
  - `id` — the ID of the imported Secret in the construct tree.
  - `attrs` — the attributes of the imported secret.

- `fromSecretCompleteArn(scope: Construct, id: string, secretCompleteArn: string): ISecret` (static) — Imports a secret by complete ARN.

  The complete ARN is the ARN with the Secrets Manager-supplied suffix.

- `fromSecretNameV2(scope: Construct, id: string, secretName: string): ISecret` (static) — Imports a secret by secret name.

  A secret with this name must exist in the same account & region.
  Replaces the deprecated `fromSecretName`.
  Please note this method returns ISecret that only contains partial ARN and could lead to AccessDeniedException
  when you pass the partial ARN to CLI or SDK to get the secret value. If your secret name ends with a hyphen and
  6 characters, you should always use fromSecretCompleteArn() to avoid potential AccessDeniedException.

- `fromSecretPartialArn(scope: Construct, id: string, secretPartialArn: string): ISecret` (static) — Imports a secret by partial ARN.

  The partial ARN is the ARN without the Secrets Manager-supplied suffix.

- `grantRead(grantee: IGrantable, versionStages?: string[]): Grant` — [disable-awslint:no-grants].

- `grantWrite(grantee: IGrantable): Grant` — [disable-awslint:no-grants].

- `isConstruct(x: any): boolean` (static) — Checks if `x` is a construct.

  Use this method instead of `instanceof` to properly detect `Construct`
  instances, even when the construct library is symlinked.

  Explanation: in JavaScript, multiple copies of the `constructs` library on
  disk are seen as independent, completely different libraries. As a
  consequence, the class `Construct` in each copy of the `constructs` library
  is seen as a different class, and an instance of one class will not test as
  `instanceof` the other class. `npm install` will not create installations
  like this, but users may manually symlink construct libraries together or
  use a monorepo tool: in those cases, multiple copies of the `constructs`
  library can be accidentally installed, and `instanceof` will behave
  unpredictably. It is safest to avoid using `instanceof`, and using
  this type-testing method instead.

  **Parameters**

  - `x` — Any object.

  **Returns:** true if `x` is an object created from a class which extends `Construct`.

- `isOwnedResource(construct: IConstruct): boolean` (static) — Returns true if the construct was created by CDK, and false otherwise.

- `isResource(construct: IConstruct): boolean` (static) — Check whether the given construct is a Resource.

- `isSecret(x: any): boolean` (static) — Return whether the given object is a Secret.

- `secretValueFromJson(jsonField: string): SecretValue` — Interpret the secret as a JSON object and return a field's value from it as a `SecretValue`.

- `toString(): string` — Returns a string representation of this construct.

- `with(...mixins: IMixin[]): IConstruct` — Applies one or more mixins to this construct.

  Mixins are applied in order. The list of constructs is captured at the
  start of the call, so constructs added by a mixin will not be visited.
  Use multiple `with()` calls if subsequent mixins should apply to added
  constructs.