export const meta = {
  title: `Access secret values`,
  description: `Configure Lambda functions to securely access secret values`,
};

Amplify CLI allows you to configure secret values that can be securely accessed from a Lambda function. Each Amplify environment can have a different secret value. This enables use cases such as different API keys for a dev and prod environment. Secrets should be used for values such as database passwords, API keys, and access tokens.

> To access non-sensitive configuration values in a Lambda function, use [environment variables](/cli/function/env-vars).

## Configuring secret values
To configure a new function with secret values, run `amplify add function`, select `yes` to the advanced settings prompt and select `yes` to the secrets configuration prompt. From there, you can specify the name and value of the secret.

```console
$ amplify add function
...
? Do you want to configure advanced settings? Yes
...
? Do you want to configure secret values this function can access? Yes
? Enter a secret name (this is the key used to look up the secret value): API_KEY
? Enter the value for API_KEY: [hidden]
? What do you want to do? (Use arrow keys)
  Add a secret
  Update a secret
  Remove secrets
> I'm done
```

To configure secrets for an existing function, run `amplify update function`, and select `Secret values configuration`. You can then add, update and remove secret values.

```console
$ amplify update function
...
? Which setting do you want to update?
  Resource access permissions
  Scheduled recurring invocation
  Lambda layers configuration
  Environment variables configuration
> Secret values configuration
? What do you want to do?
> Add a secret
  Update a secret
  Remove secrets
  I'm done
```

> Note: Amplify CLI never stores secrets locally. All secret values are immediately stored in [AWS Parameter Store](https://docs.aws.amazon.com/systems-manager/latest/userguide/systems-manager-parameter-store.html) using the SecureString parameter type.

## Accessing the values in your function
To access the secret values in your Lambda function, use the [AWS SSM GetParameter API](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_GetParameter.html). Amplify CLI will automatically supply the SSM parameter name of the secret as an environment variable to the function. This value can be passed into the API call as the "Name" to retrieve the value. Ensure that the API call has "WithDecryption" specified as `true`.

If your Lambda function is using the Node.js runtime, a comment block will be placed at the top of your `index.js` file with example code to retrieve the secret values.

```js
const aws = require('aws-sdk');

const { Parameters } = await (new aws.SSM())
  .getParameters({
    Names: ["EXAMPLE_SECRET_1", "EXAMPLE_SECRET_2"].map(secretName => process.env[secretName]),
    WithDecryption: true,
  })
  .promise();

// Parameters will be of the form { Name: 'secretName', Value: 'secretValue', ... }[]
```

## Multi-environment flows
When creating a new Amplify environment using `amplify env add`, Amplify CLI asks if you want to apply all secret values to the new environment or modify them. If you choose to apply the existing values, you can still make edits anytime using `amplify update function`.

When creating a new Amplify environment using `amplify env add --envName <new env name> --yes`, Amplify CLI will apply all secret values from the current environment to the new environment.

In multi-environment workflows, you may have added a new secret in one Amplify environment and then checked out a different Amplify environment. In this case, on the next `amplify push`. Amplify CLI will detect that there is a new secret that does not have a value specified in the current environment and prompt for one. Running `amplify push --yes` in this case will fail with a message explaining the missing secret values.

In [**git-based** multi-environment workflows](/cli/teams/overview), you may run into errors during deployment. For example, this happens when you add a secret in `envA` (corresponding to a git branch `branchA`), then `amplify env checkout envB` and `git checkout branchB` and `git merge` branchA into branchB. Upon pushing `envB`, Amplify CLI detects that a new secret has been added but can't infer a value for it. To resolve this issue, run the following commands in the terminal:

1. `amplify env checkout <failing env name>`
2. `amplify push` - when prompted, enter a new value for the secret(s)
3. `git commit`
4. `git push`