# Key

Defines a KMS key.

Extends: Construct › Resource › Key
Implements: IResource, IKey, IEnvironmentAware, IKeyRef, IConstruct, IDependable

- CloudFormation: [`AWS::KMS::Key`](https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-resource-kms-key.html)
- L1 type: [`CfnKey`](/cdk/api/v2/docs/aws-cdk-lib.aws_kms.CfnKey.html)
- Source: [`aws-kms/lib/key.ts`](https://github.com/aws/aws-cdk/blob/v2.275.0/packages/aws-cdk-lib/aws-kms/lib/key.ts#L584)
- Type last changed: v2.237.0 · 2 Feb 2026

## Example

```ts
declare const vpc: ec2.Vpc;
const engine = rds.DatabaseInstanceEngine.postgres({ version: rds.PostgresEngineVersion.VER_16_3 });
const myKey = new kms.Key(this, 'MyKey');

new rds.DatabaseInstance(this, 'InstanceWithCustomizedSecret', {
  engine,
  vpc,
  credentials: rds.Credentials.fromGeneratedSecret('postgres', {
    secretName: 'my-cool-name',
    encryptionKey: myKey,
    excludeCharacters: '!&*^#@()',
    replicaRegions: [{ region: 'eu-west-1' }, { region: 'eu-west-2' }],
  }),
});
```

## Initializer

```ts
new Key(scope: Construct, id: string, props?: KeyProps)
```

## Construct Props

- `admins`: [IPrincipal](/cdk/api/v2/docs/aws-cdk-lib.aws_iam.IPrincipal.html)[] = [] — A list of principals to add as key administrators to the key policy.

  Key administrators have permissions to manage the key (e.g., change permissions, revoke), but do not have permissions
  to use the key in cryptographic operations (e.g., encrypt, decrypt).

  These principals will be added to the default key policy (if none specified), or to the specified policy (if provided).

- `alias`: string — Initial alias to add to the key.

  **Default:** No alias is added for the key.

  More aliases can be added later by calling `addAlias`.

- `description`: string — A description of the key.

  **Default:** No description.

  Use a description that helps your users decide
  whether the key is appropriate for a particular task.

- `enabled`: boolean — Indicates whether the key is available for use.

  **Default:** Key is enabled.

- `enableKeyRotation`: boolean = false — Indicates whether AWS KMS rotates the key.

- `keySpec`: [KeySpec](/cdk/api/v2/docs/aws-cdk-lib.aws_kms.KeySpec.html) = KeySpec.SYMMETRIC_DEFAULT — The cryptographic configuration of the key. The valid value depends on usage of the key.

  IMPORTANT: If you change this property of an existing key, the existing key is scheduled for deletion
  and a new key is created with the specified value.

- `keyUsage`: [KeyUsage](/cdk/api/v2/docs/aws-cdk-lib.aws_kms.KeyUsage.html) = KeyUsage.ENCRYPT_DECRYPT — The cryptographic operations for which the key can be used.

  IMPORTANT: If you change this property of an existing key, the existing key is scheduled for deletion
  and a new key is created with the specified value.

- `multiRegion`: boolean = false — Creates a multi-Region primary key that you can replicate in other AWS Regions.

  You can't change the `multiRegion` value after the KMS key is created.

  IMPORTANT: If you change the value of the `multiRegion` property on an existing KMS key, the update request fails,
  regardless of the value of the UpdateReplacePolicy attribute.
  This prevents you from accidentally deleting a KMS key by changing an immutable property value.

- `pendingWindow`: [Duration](/cdk/api/v2/docs/aws-cdk-lib.Duration.html) — Specifies the number of days in the waiting period before AWS KMS deletes a CMK that has been removed from a CloudFormation stack.

  **Default:** 30 days

  When you remove a customer master key (CMK) from a CloudFormation stack, AWS KMS schedules the CMK for deletion
  and starts the mandatory waiting period. The PendingWindowInDays property determines the length of waiting period.
  During the waiting period, the key state of CMK is Pending Deletion, which prevents the CMK from being used in
  cryptographic operations. When the waiting period expires, AWS KMS permanently deletes the CMK.

  Enter a value between 7 and 30 days.

- `policy`: [PolicyDocument](/cdk/api/v2/docs/aws-cdk-lib.aws_iam.PolicyDocument.html) — Custom policy document to attach to the KMS key.

  **Default:** A policy document with permissions for the account root to administer the key will be created.

  NOTE - If the `@aws-cdk/aws-kms:defaultKeyPolicies` feature flag is set (the default for new projects),
  this policy will *override* the default key policy and become the only key policy for the key. If the
  feature flag is not set, this policy will be appended to the default key policy.

- `removalPolicy`: [RemovalPolicy](/cdk/api/v2/docs/aws-cdk-lib.RemovalPolicy.html) = RemovalPolicy.Retain — Whether the encryption key should be retained when it is removed from the Stack.

  This is useful when one wants to
  retain access to data that was encrypted with a key that is being retired.

- `rotationPeriod`: [Duration](/cdk/api/v2/docs/aws-cdk-lib.Duration.html) — The period between each automatic rotation.

  **Default:** set by CFN to 365 days.

## Properties

- `DEFAULT_DUMMY_KEY_ID`: string (static) — The default key id of the dummy key.

  This value is used as a dummy key id if the key was not found
  by the `Key.fromLookup()` method.

- `env`: [ResourceEnvironment](/cdk/api/v2/docs/aws-cdk-lib.interfaces.ResourceEnvironment.html) — 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.

- `grants`: [KeyGrants](/cdk/api/v2/docs/aws-cdk-lib.aws_kms.KeyGrants.html) — Collection of grant methods for a Key.

- `keyArn`: string — The ARN of the key.

- `keyId`: string — The ID of the key (the part that looks something like: 1234abcd-12ab-34cd-56ef-1234567890ab).

- `keyRef`: [KeyReference](/cdk/api/v2/docs/aws-cdk-lib.interfaces.aws_kms.KeyReference.html) — A reference to a Key resource.

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

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

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

## Methods

- `addAlias(aliasName: string): Alias` — Defines a new alias for the key.

- `addToResourcePolicy(statement: PolicyStatement, allowNoOp?: boolean): AddToResourcePolicyResult` — Adds a statement to the KMS key resource policy.

  **Parameters**

  - `statement` — The policy statement to add.
  - `allowNoOp` — If this is set to `false` and there is no policy defined (i.e. external key), the operation will fail. Otherwise, it will 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`).

- `fromCfnKey(cfnKey: CfnKey): IKey` (static) — Create a mutable `IKey` based on a low-level `CfnKey`.

  This is most useful when combined with the cloudformation-include module.
  This method is different than `fromKeyArn()` because the `IKey`
  returned from this method is mutable;
  meaning, calling any mutating methods on it,
  like `IKey.addToResourcePolicy()`,
  will actually be reflected in the resulting template,
  as opposed to the object returned from `fromKeyArn()`,
  on which calling those methods would have no effect.

- `fromKeyArn(scope: Construct, id: string, keyArn: string): IKey` (static) — Import an externally defined KMS Key using its ARN.

  **Parameters**

  - `scope` — the construct that will "own" the imported key.
  - `id` — the id of the imported key in the construct tree.
  - `keyArn` — the ARN of an existing KMS key.

- `fromLookup(scope: Construct, id: string, options: KeyLookupOptions): IKey` (static) — Import an existing Key by querying the AWS environment this stack is deployed to.

  This function only needs to be used to use Keys not defined in your CDK
  application. If you are looking to share a Key between stacks, you can
  pass the `Key` object between stacks and use it as normal. In addition,
  it's not necessary to use this method if an interface accepts an `IKey`.
  In this case, `Alias.fromAliasName()` can be used which returns an alias
  that extends `IKey`.

  Calling this method will lead to a lookup when the CDK CLI is executed.
  You can therefore not use any values that will only be available at
  CloudFormation execution time (i.e., Tokens).

  If you set `returnDummyKeyOnMissing` to `true` in `options` and the key was not found,
  this method will return a dummy key with a key id '1234abcd-12ab-34cd-56ef-1234567890ab'.
  The value of the dummy key id can also be referenced using the `Key.DEFAULT_DUMMY_KEY_ID`
  variable, and you can check if the key is a dummy key by using the `Key.isLookupDummy()`
  method.

  The Key information will be cached in `cdk.context.json` and the same Key
  will be used on future runs. To refresh the lookup, you will have to
  evict the value from the cache using the `cdk context` command. See
  https://docs.aws.amazon.com/cdk/latest/guide/context.html for more information.

- `grant(grantee: IGrantable, ...actions: string[]): Grant` — Grant the indicated permissions on this key to the given principal.

  This modifies both the principal's policy as well as the resource policy,
  since the default CloudFormation setup for KMS keys is that the policy
  must not be empty and so default grants won't work.

  [disable-awslint:no-grants]

- `grantAdmin(grantee: IGrantable): Grant` — Grant admins permissions using this key to the given principal.

  Key administrators have permissions to manage the key (e.g., change permissions, revoke), but do not have permissions
  to use the key in cryptographic operations (e.g., encrypt, decrypt).

  [disable-awslint:no-grants]

- `grantDecrypt(grantee: IGrantable): Grant` — Grant decryption permissions using this key to the given principal.

  [disable-awslint:no-grants]

- `grantEncrypt(grantee: IGrantable): Grant` — Grant encryption permissions using this key to the given principal.

  [disable-awslint:no-grants]

- `grantEncryptDecrypt(grantee: IGrantable): Grant` — Grant encryption and decryption permissions using this key to the given principal.

  [disable-awslint:no-grants]

- `grantGenerateMac(grantee: IGrantable): Grant` — Grant permissions to generating MACs to the given principal.

  [disable-awslint:no-grants]

- `grantSign(grantee: IGrantable): Grant` — Grant sign permissions using this key to the given principal.

  [disable-awslint:no-grants]

- `grantSignVerify(grantee: IGrantable): Grant` — Grant sign and verify permissions using this key to the given principal.

  [disable-awslint:no-grants]

- `grantVerify(grantee: IGrantable): Grant` — Grant verify permissions using this key to the given principal.

  [disable-awslint:no-grants]

- `grantVerifyMac(grantee: IGrantable): Grant` — Grant permissions to verifying MACs to the given principal.

  [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`.

- `isLookupDummy(key: IKeyRef): boolean` (static) — Checks if the key returned by the `Key.fromLookup()` method is a dummy key, i.e., a key that was not found.

  This method can only be used if the `returnDummyKeyOnMissing` option
  is set to `true` in the `options` for the `Key.fromLookup()` method.

- `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.

- `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.