Use AWS Secrets Manager secrets in AWS Lambda functions - AWS Secrets Manager

Use AWS Secrets Manager secrets in AWS Lambda functions

You can use the AWS Parameters and Secrets Lambda Extension to retrieve and cache AWS Secrets Manager secrets in Lambda functions without using an SDK. Retrieving a cached secret is faster than retrieving it from Secrets Manager. Because there is a cost for calling Secrets Manager APIs, using a cache can reduce your costs. The extension can retrieve both Secrets Manager secrets and Parameter Store parameters. For information about Parameter Store, see Parameter Store integration with Lambda extensions in the AWS Systems Manager User Guide.

A Lambda extension is a companion process that adds to the capabilities of a Lambda function. For more information, see Lambda extensions in the Lambda Developer Guide. Lambda logs execution information about the extension along with the function by using Amazon CloudWatch Logs. By default, the extension logs a minimal amount of information to CloudWatch. To log more details, set the environment variable PARAMETERS_SECRETS_EXTENSION_LOG_LEVEL to debug.

The extension makes requests to localhost port 2773. You can configure the port by setting the environment variable PARAMETERS_SECRETS_EXTENSION_HTTP_PORT.

Lambda instantiates separate instances corresponding to the concurrency level that your function requires. Each instance is isolated and maintains its own local cache of your configuration data. For more information about Lambda instances and concurrency, see Managing concurrency for a Lambda function in the Lambda Developer Guide.

To add the extension for ARM, you must use the arm64 architecture for your Lambda function. For more information, see Lambda instruction set architectures in the Lambda Developer Guide. The extension supports ARM in the following Regions: Asia Pacific (Mumbai), US East (Ohio), Europe (Ireland), Europe (Frankfurt), US East (N. Virginia), Europe (London), Asia Pacific (Tokyo), US West (Oregon), Asia Pacific (Singapore), and Asia Pacific (Sydney).

To use the AWS Parameters and Secrets Lambda Extension

  1. Add the layer to your function by doing one of the following:

    • Open the AWS Lambda console at

      1. Choose your function, choose Layers, and then choose Add a layer.

      2. On the Add layer page, for AWS layers, choose AWS Parameters and Secrets Lambda Extension, and then choose Add.

    • Use the following AWS CLI command with the appropriate ARN for your Region.

      aws lambda update-function-configuration \ --function-name my-function \ --layers LayerARN
  2. Grant permissions to the Lambda execution role to be able to access secrets:

  3. Configure the cache with Lambda environment variables.

  4. To retrieve secrets from the extension cache, you first need to add the X-AWS-Parameters-Secrets-Token to the request header. Set the token to AWS_SESSION_TOKEN, which is provided by Lambda for all running functions. Using this header indicates that the caller is within the Lambda environment.

    The following Python example shows how to add the header.

    import os headers = {"X-Aws-Parameters-Secrets-Token": os.environ.get('AWS_SESSION_TOKEN')}
  5. To retrieve a secret within the Lambda function, use one of the following HTTP GET requests:

    • To retrieve a secret, for secretId, use the ARN or name of the secret.

      GET: /secretsmanager/get?secretId=secretId
    • To retrieve the previous secret value or a specific version by staging label, for secretId, use the ARN or name of the secret, and for versionStage, use the staging label.

      GET: /secretsmanager/get?secretId=secretId&versionStage=AWSPREVIOUS
    • To retrieve a specific secret version by ID, for secretId, use the ARN or name of the secret, and for versionId, use the version ID.

      GET: /secretsmanager/get?secretId=secretId&versionId=versionId

    Example Retrieve a secret (Python)

    The following Python example shows how to retrieve a secret and parse the result using json.loads.

    secrets_extension_endpoint = "http://localhost:" + \ secrets_extension_http_port + \ "/secretsmanager/get?secretId=" + \ <secret_name> r = requests.get(secrets_extension_endpoint, headers=headers) secret = json.loads(r.text)["SecretString"] # load the Secrets Manager response into a Python dictionary, access the secret

AWS Parameters and Secrets Lambda Extension environment variables

You can configure the extension with the following environment variables.

For information about how to use environment variables, see Using Lambda environment variables in the Lambda Developer Guide.


Set to true to cache parameters and secrets. Set to false for no caching. Default is true.


The maximum number of secrets and parameters to cache. Must be a value from 0 to 1000. A value of 0 means there is no caching. This variable is ignored if both SSM_PARAMETER_STORE _TTL and SECRETS_MANAGER_TTL are 0. Default is 1000.


The port for the local HTTP server. Default is 2773.


The level of logging the extension provides: debug, info, warn, error, or none. Set to debug to see the cache configuration. Default is info.


Maximum number of connections for HTTP clients that the extension uses to make requests to Parameter Store or Secrets Manager. This is a per-client configuration. Default is 3.


Timeout for requests to Secrets Manager in milliseconds. A value of 0 means there is no timeout. Default is 0.


TTL of a secret in the cache in seconds. A value of 0 means there is no caching. The maximum is 300 seconds. This variable is ignored if PARAMETERS_SECRETS_CACHE_SIZE is 0. Default is 300 seconds.


Timeout for requests to Parameter Store in milliseconds. A value of 0 means there is no timeout. Default is 0.


TTL of a parameter in the cache in seconds. A value of 0 means there is no caching. The maximum is 300 seconds. This variable is ignored if PARAMETERS_SECRETS_CACHE_SIZE is 0. Default is 300 seconds.

AWS Parameters and Secrets Lambda Extension ARNs

Region ARN

US East (N. Virginia)



US East (Ohio)



US West (N. California)


US West (Oregon)



Canada (Central)


Europe (Frankfurt)



Europe (Ireland)



Europe (London)



Europe (Paris)


Europe (Stockholm)


Europe (Milan)


China (Beijing)


China (Ningxia)


Asia Pacific (Hong Kong)


Asia Pacific (Tokyo)



Asia Pacific (Osaka)


Asia Pacific (Seoul)


Asia Pacific (Singapore)



Asia Pacific (Sydney)



Asia Pacific (Jakarta)


Asia Pacific (Mumbai)



South America (São Paulo)


Africa (Cape Town)


Middle East (UAE) arn:aws:lambda:me-central-1:858974508948:layer:AWS-Parameters-and-Secrets-Lambda-Extension:2

Middle East (Bahrain)


AWS GovCloud (US-East)


AWS GovCloud (US-West)