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.

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.

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

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

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', ... }[]

const { SSMClient, GetParametersCommand } = require("@aws-sdk/client-ssm");

const client = new SSMClient();

const command = new GetParametersCommand({
  Names: ["EXAMPLE_SECRET_1", "EXAMPLE_SECRET_2"].map(
    (secretName) => process.env[secretName]
  ),
  WithDecryption: true,
});

client
  .send(command)
  .then((response) => {
    const { Parameters } = response;
    console.log(Parameters);
  })
  .catch((error) => {
    console.error(error);
  });

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, 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