API Reference
    Preparing search index...

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

    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.

    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');
    };

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

    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.

    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 });
    };

    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.

    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 });
    };

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

    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' });
    };

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

    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,
    },
    });
    };

    This object accepts the same options as the AWS SDK v3 for JavaScript Secrets Manager 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.

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

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

    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.

    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,
    });

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

    For more usage examples, see our documentation.

    Hierarchy (View Summary)

    Index

    Constructors

    Properties

    client: SecretsManagerClient
    store: Map<string, ExpirableValue>

    Methods

    • Retrieve a configuration from AWS Secrets Manager.

      Parameters

      • name: string

        Name of the configuration or its ID

      • Optionaloptions: SecretsGetOptions

        SDK options to propagate to the AWS SDK v3 for JavaScript client

      Returns Promise<undefined | string | Uint8Array<ArrayBufferLike>>

    • Retrieving multiple parameter values is not supported with AWS Secrets Manager.

      Parameters

      • _path: string
      • Optional_options: unknown

      Returns Promise<undefined | Record<string, unknown>>

      Not Implemented Error.

    • Add a value to the cache.

      Parameters

      • key: string

        Key of the cached value

      • value: unknown

        Value to be cached

      • maxAge: number

        Maximum age in seconds for the value to be cached

      Returns void