Class SecretsProvider

Intro

The Parameters utility provides a SecretsProvider that allows to retrieve secrets from AWS Secrets Manager.

Getting started

This utility supports AWS SDK v3 for JavaScript only (@aws-sdk/client-secrets-manager). This allows the utility to be modular, and you to install only the SDK packages you need and keep your bundle size small.

Basic usage

Example

import { SecretsProvider } from '@aws-lambda-powertools/parameters/secrets';

const secretsProvider = new SecretsProvider();

export const handler = async (): Promise<void> => {
  // Retrieve a secret
  const secret = await secretsProvider.get('my-secret');
};
Copy

If you want to retrieve secrets without customizing the provider, you can use the getSecret function instead.

Advanced usage

Caching

By default, the provider will cache parameters retrieved in-memory for 5 seconds. You can adjust how long values should be kept in cache by using the maxAge parameter.

Example

import { SecretsProvider } from '@aws-lambda-powertools/parameters/secrets';

const secretsProvider = new SecretsProvider();

export const handler = async (): Promise<void> => {
  // Retrieve a secret and cache it for 10 seconds
  const secret = await secretsProvider.get('my-secret', { maxAge: 10 });
};
Copy

If instead you'd like to always ensure you fetch the latest parameter from the store regardless if already available in cache, use the forceFetch parameter.

Example

import { SecretsProvider } from '@aws-lambda-powertools/parameters/secrets';

const secretsProvider = new SecretsProvider();

export const handler = async (): Promise<void> => {
  // Retrieve a secret and always fetch the latest value
  const secret = await secretsProvider.get('my-secret', { forceFetch: true });
};
Copy

Transformations

For parameters stored in JSON or Base64 format, you can use the transform argument for deserialization.

Example

import { SecretsProvider } from '@aws-lambda-powertools/parameters/secrets';

const secretsProvider = new SecretsProvider();

export const handler = async (): Promise<void> => {
  // Retrieve a secret and parse it as JSON
  const secret = await secretsProvider.get('my-secret', { transform: 'json' });
};
Copy

Extra SDK options

When retrieving a secret, you can pass extra options to the AWS SDK v3 for JavaScript client by using the sdkOptions parameter.

Example

import { SecretsProvider } from '@aws-lambda-powertools/parameters/secrets';

const secretsProvider = new SecretsProvider();

export const handler = async (): Promise<void> => {
  // Retrieve a secret and pass extra options to the AWS SDK v3 for JavaScript client
  const secret = await secretsProvider.get('my-secret', {
    sdkOptions: {
      VersionId: 1,
    },
  });
};
Copy

This object accepts the same options as the AWS SDK v3 for JavaScript Secrets Manager client.

Customize AWS SDK v3 for JavaScript client

By default, the provider will create a new Secrets Manager client using the default configuration.

You can customize the client by passing a custom configuration object to the provider.

Example

import { SecretsProvider } from '@aws-lambda-powertools/parameters/secrets';

const secretsProvider = new SecretsProvider({
 clientConfig: { region: 'eu-west-1' },
});
Copy

This object accepts the same options as the AWS SDK v3 for JavaScript Secrets Manager client.

Otherwise, if you want to use a custom client altogether, you can pass it to the provider.

Example

import { SecretsProvider } from '@aws-lambda-powertools/parameters/secrets';
import { SecretsManagerClient } from '@aws-sdk/client-secrets-manager';

const client = new SecretsManagerClient({ region: 'eu-west-1' });
const secretsProvider = new SecretsProvider({
 awsSdkV3Client: client,
});
Copy

This object must be an instance of the AWS SDK v3 for JavaScript Secrets Manager client.

For more usage examples, see our documentation.

Implements

See

https://docs.powertools.aws.dev/lambda/typescript/latest/utilities/parameters/