# SecretValue

Work with secret values in the CDK.

Constructs that need secrets will declare parameters of type `SecretValue`.

The actual values of these secrets should not be committed to your
repository, or even end up in the synthesized CloudFormation template. Instead, you should
store them in an external system like AWS Secrets Manager or SSM Parameter
Store, and you can reference them by calling `SecretValue.secretsManager()` or
`SecretValue.ssmSecure()`.

You can use `SecretValue.unsafePlainText()` to construct a `SecretValue` from a
literal string, but doing so is highly discouraged.

To make sure secret values don't accidentally end up in readable parts
of your infrastructure definition (such as the environment variables
of an AWS Lambda Function, where everyone who can read the function
definition has access to the secret), using secret values directly is not
allowed. You must pass them to constructs that accept `SecretValue`
properties, which are guaranteed to use the value only in CloudFormation
properties that are write-only.

If you are sure that what you are doing is safe, you can call
`secretValue.unsafeUnwrap()` to access the protected string of the secret
value.

(If you are writing something like an AWS Lambda Function and need to access
a secret inside it, make the API call to `GetSecretValue` directly inside
your Lamba's code, instead of using environment variables.)

Extends: Intrinsic › SecretValue
Implements: IResolvable

- Source: [`core/lib/secret-value.ts`](https://github.com/aws/aws-cdk/blob/v2.275.0/packages/aws-cdk-lib/core/lib/secret-value.ts#L44)
- Type last changed: v2.224.0 · 13 Nov 2025

## Example

```ts
const amplifyApp = new amplify.App(this, 'MyApp', {
  sourceCodeProvider: new amplify.GitHubSourceCodeProvider({
    owner: '<user>',
    repository: '<repo>',
    oauthToken: SecretValue.secretsManager('my-github-token'),
  }),
  basicAuth: amplify.BasicAuth.fromCredentials('username', SecretValue.secretsManager('my-github-token')),
});
```

## Initializer

```ts
new SecretValue(protectedValue: any, options?: IntrinsicProps)
```

## Properties

- `creationStack`: string[] — The captured stack trace which represents the location in which this token was created.

- `typeHint`: [ResolutionTypeHint](/cdk/api/v2/docs/aws-cdk-lib.ResolutionTypeHint.html) — Type that the Intrinsic is expected to evaluate to.

## Methods

- `cfnDynamicReference(ref: CfnDynamicReference): SecretValue // chainable` (static) — Obtain the secret value through a CloudFormation dynamic reference.

  If possible, use `SecretValue.ssmSecure` or `SecretValue.secretsManager` directly.

  **Parameters**

  - `ref` — The dynamic reference to use.

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

  **Parameters**

  - `secretId` — The ID or ARN of the secret.
  - `options` — Options.

- `cfnParameter(param: CfnParameter): SecretValue // chainable` (static) — Obtain the secret value through a CloudFormation parameter.

  Generally, this is not a recommended approach. AWS Secrets Manager is the
  recommended way to reference secrets.

  **Parameters**

  - `param` — The CloudFormation parameter to use.

- `isSecretValue(x: any): boolean` (static) — Test whether an object is a SecretValue.

- `plainText(secret: string): SecretValue // chainable` (static) — Use `unsafePlainText()` instead.

  Do not use this method for any secrets that you care about! The value
  will be visible to anyone who has access to the CloudFormation template
  (via the AWS Console, SDKs, or CLI).

  The only reasonable use case for using this method is when you are testing.

- `resolve(context: IResolveContext): any` — Resolve the secret.

  If the feature flag is not set, resolve as normal. Otherwise, throw a descriptive
  error that the usage guard is missing.

- `resourceAttribute(attr: string): SecretValue // chainable` (static) — Use a resource's output as secret value.

- `secretsManager(secretId: string, options?: SecretsManagerSecretOptions): SecretValue // chainable` (static) — Creates a `SecretValue` with a value which is dynamically loaded from AWS Secrets Manager.

  If you rotate the value in the Secret, you must also change at least one property
  on the resource where you are using the secret, to force CloudFormation to re-read the secret.

  **Parameters**

  - `secretId` — The ID or ARN of the secret.
  - `options` — Options.

- `ssmSecure(parameterName: string, version?: string): SecretValue // chainable` (static) — Use a secret value stored from a Systems Manager (SSM) parameter.

  This secret source in only supported in a limited set of resources and
  properties. [Click here for the list of supported
  properties](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/dynamic-references.html#template-parameters-dynamic-patterns-resources).

  **Parameters**

  - `parameterName` — The name of the parameter in the Systems Manager Parameter Store.
  - `version` — An integer that specifies the version of the parameter to use.

- `toJSON(): any` — Turn this Token into JSON.

  Called automatically when JSON.stringify() is called on a Token.

- `toString(): string` — Convert an instance of this Token to a string.

  This method will be called implicitly by language runtimes if the object
  is embedded into a string. We treat it the same as an explicit
  stringification.

- `toStringList(): string[]` — Convert an instance of this Token to a string list.

  This method will be called implicitly by language runtimes if the object
  is embedded into a list. We treat it the same as an explicit
  stringification.

- `unsafePlainText(secret: string): SecretValue // chainable` (static) — Construct a literal secret value for use with secret-aware constructs.

  Do not use this method for any secrets that you care about! The value
  will be visible to anyone who has access to the CloudFormation template
  (via the AWS Console, SDKs, or CLI).

  The primary use case for using this method is when you are testing.

  The other use case where this is appropriate is when constructing a JSON secret.
  For example, a JSON secret might have multiple fields where only some are actual
  secret values.

  ```ts
  declare const secret: SecretValue;
  const jsonSecret = {
    username: SecretValue.unsafePlainText('myUsername'),
    password: secret,
  };
  ```

- `unsafeUnwrap(): string` — Disable usage protection on this secret.

  Call this to indicate that you want to use the secret value held by this
  object in an unchecked way. If you don't call this method, using the secret
  value directly in a string context or as a property value somewhere will
  produce an error.

  This method has 'unsafe' in the name on purpose! Make sure that the
  construct property you are using the returned value in is does not end up
  in a place in your AWS infrastructure where it could be read by anyone
  unexpected.

  When in doubt, don't call this method and only pass the object to constructs that
  accept `SecretValue` parameters.