Secrets

AWS Secrets Manager parameter retrieval and caching utility

CLASS	DESCRIPTION
`SecretsProvider`	AWS Secrets Manager Parameter Provider

FUNCTION	DESCRIPTION
`get_secret`	Retrieve a parameter value from AWS Secrets Manager
`get_secrets_by_name`	Retrieve multiple secrets by name from AWS Secrets Manager
`set_secret`	Modify the details of a secret or create a new secret if it doesn't already exist.

SecretsProvider ¶

SecretsProvider(config: Config | None = None, boto_config: Config | None = None, boto3_session: Session | None = None, boto3_client: SecretsManagerClient | None = None)

Bases: BaseProvider

AWS Secrets Manager Parameter Provider

PARAMETER DESCRIPTION

config

Botocore configuration to pass during client initialization

TYPE: Config | None DEFAULT: None

boto3_session

1	`Boto3 session to create a boto3_client from`

TYPE: Session DEFAULT: None

boto3_client

Boto3 SecretsManager Client to use, boto3_session will be ignored if both are provided

TYPE: SecretsManagerClient | None DEFAULT: None

Example

Retrieves a parameter value from Secrets Manager

>>> from aws_lambda_powertools.utilities.parameters import SecretsProvider
>>> secrets_provider = SecretsProvider()
>>>
>>> value = secrets_provider.get("my-parameter")
>>>
>>> print(value)
My parameter value

Retrieves a parameter value from Secrets Manager in another AWS region

>>> from botocore.config import Config
>>> from aws_lambda_powertools.utilities.parameters import SecretsProvider
>>>
>>> config = Config(region_name="us-west-1")
>>> secrets_provider = SecretsProvider(config=config)
>>>
>>> value = secrets_provider.get("my-parameter")
>>>
>>> print(value)
My parameter value

Retrieves a parameter value from Secrets Manager passing options to the SDK call

>>> from aws_lambda_powertools.utilities.parameters import SecretsProvider
>>> secrets_provider = SecretsProvider()
>>>
>>> value = secrets_provider.get("my-parameter", VersionId="f658cac0-98a5-41d9-b993-8a76a7799194")
>>>
>>> print(value)
My parameter value

METHOD	DESCRIPTION
`get_multiple`	Retrieve multiple secrets by name from AWS Secrets Manager
`set`	Modify the details of a secret or create a new secret if it doesn't already exist.

Source code in aws_lambda_powertools/utilities/parameters/secrets.py

def __init__(
    self,
    config: Config | None = None,
    boto_config: Config | None = None,
    boto3_session: boto3.session.Session | None = None,
    boto3_client: SecretsManagerClient | None = None,
):
    """
    Initialize the Secrets Manager client
    """
    if config:
        warnings.warn(
            message="The 'config' parameter is deprecated in V3 and will be removed in V4. "
            "Please use 'boto_config' instead.",
            category=PowertoolsDeprecationWarning,
            stacklevel=2,
        )

    if boto3_client is None:
        boto3_session = boto3_session or boto3.session.Session()
        boto3_client = boto3_session.client("secretsmanager", config=boto_config or config)
    self.client = boto3_client

    super().__init__(client=self.client)

get_multiple ¶

get_multiple(names: list[str], max_age: int | None = None, transform: TransformOptions = None, raise_on_transform_error: bool = False, force_fetch: bool = False, **sdk_options) -> dict[str, Any]

Retrieve multiple secrets by name from AWS Secrets Manager

PARAMETER	DESCRIPTION
`names`	List of secret names to retrieve TYPE: `list[str]`
`max_age`	Maximum age of the cached value TYPE: `int \| None` DEFAULT: `None`
`transform`	Optional transformation of the parameter value. Supported values are "json" for JSON strings and "binary" for base 64 encoded values. TYPE: `TransformOptions` DEFAULT: `None`
`raise_on_transform_error`	Raises an exception if any transform fails, otherwise this will return a None value for each transform that failed TYPE: `bool` DEFAULT: `False`
`force_fetch`	Force update even before a cached item has expired, defaults to False TYPE: `bool` DEFAULT: `False`
`sdk_options`	Arguments that will be passed directly to the underlying API call DEFAULT: `{}`

RETURNS	DESCRIPTION
`dict[str, str \| bytes \| dict]`	Dictionary mapping secret names to their values

RAISES	DESCRIPTION
`GetParameterError`	When the parameter provider fails to retrieve secrets
`TransformParameterError`	When the parameter provider fails to transform a secret value

Source code in aws_lambda_powertools/utilities/parameters/secrets.py

def get_multiple(  # type: ignore[override]
    self,
    names: list[str],
    max_age: int | None = None,
    transform: TransformOptions = None,
    raise_on_transform_error: bool = False,
    force_fetch: bool = False,
    **sdk_options,
) -> dict[str, Any]:
    """
    Retrieve multiple secrets by name from AWS Secrets Manager

    Parameters
    ----------
    names: list[str]
        List of secret names to retrieve
    max_age: int, optional
        Maximum age of the cached value
    transform: str, optional
        Optional transformation of the parameter value. Supported values
        are "json" for JSON strings and "binary" for base 64 encoded values.
    raise_on_transform_error: bool, optional
        Raises an exception if any transform fails, otherwise this will
        return a None value for each transform that failed
    force_fetch: bool, optional
        Force update even before a cached item has expired, defaults to False
    sdk_options: dict, optional
        Arguments that will be passed directly to the underlying API call

    Returns
    -------
    dict[str, str | bytes | dict]
        Dictionary mapping secret names to their values

    Raises
    ------
    GetParameterError
        When the parameter provider fails to retrieve secrets
    TransformParameterError
        When the parameter provider fails to transform a secret value
    """
    if not names:
        raise GetSecretError("You must provide at least one secret name")

    # Create a unique cache key for this batch of secrets
    # Use sorted names to ensure consistent caching regardless of order
    cache_key_name = "|".join(sorted(names))
    key = self._build_cache_key(name=cache_key_name, transform=transform, is_nested=True)

    # If max_age is not set, resolve it from the environment variable, defaulting to DEFAULT_MAX_AGE_SECS
    max_age = resolve_max_age(env=os.getenv(constants.PARAMETERS_MAX_AGE_ENV, DEFAULT_MAX_AGE_SECS), choice=max_age)

    if not force_fetch and self.has_not_expired_in_cache(key):
        cached_values = self.fetch_from_cache(key)
        # Return only the requested secrets from cache (in case cache has more)
        return {name: cached_values[name] for name in names if name in cached_values}

    try:
        values = self._get_multiple(names, **sdk_options)
    except Exception as exc:
        raise GetSecretError(str(exc)) from exc

    if transform:
        # Transform each secret value
        transformed_values = {}
        for name, value in values.items():
            try:
                transformed_values[name] = transform_value(
                    key=name,
                    value=value,
                    transform=transform,
                    raise_on_transform_error=raise_on_transform_error,
                )
            except TransformParameterError:
                if raise_on_transform_error:
                    raise
                transformed_values[name] = None  # pragma: no cover
        values = transformed_values

    # Cache the results
    self.add_to_cache(key=key, value=values, max_age=max_age)

    return values

set ¶

set(name: str, value: str | bytes | dict, *, client_request_token: str | None = None, **sdk_options) -> CreateSecretResponseTypeDef

Modify the details of a secret or create a new secret if it doesn't already exist.

We aim to minimize API calls by assuming that the secret already exists and needs updating. If it doesn't exist, we attempt to create a new one. Refer to the following workflow for a better understanding:

              ┌────────────────────────┐      ┌─────────────────┐
    ┌───────▶│Resource NotFound error?│────▶│Create Secret API│─────┐
    │         └────────────────────────┘      └─────────────────┘     │
    │                                                                 │
    │                                                                 │
    │                                                                 ▼

┌─────────────────┐ ┌─────────────────────┐ │Update Secret API│────────────────────────────────────────────▶│ Return or Exception │ └─────────────────┘ └─────────────────────┘

PARAMETER	DESCRIPTION
`name`	The ARN or name of the secret to add a new version to or create a new one. TYPE: `str`
`value`	Specifies text data that you want to encrypt and store in this new version of the secret. TYPE: `str \| bytes \| dict`
`client_request_token`	This value helps ensure idempotency. It's recommended that you generate a UUID-type value to ensure uniqueness within the specified secret. This value becomes the VersionId of the new version. This field is auto-populated if not provided, but no idempotency will be enforced this way. TYPE: `str \| None` DEFAULT: `None`
`sdk_options`	Dictionary of options that will be passed to the Secrets Manager update_secret API call DEFAULT: `{}`

RAISES	DESCRIPTION
`SetSecretError`	When attempting to update or create a secret fails.

Example

Sets a secret*

>>> from aws_lambda_powertools.utilities import parameters
>>>
>>> parameters.set_secret(name="llamas-are-awesome", value="supers3cr3tllam@passw0rd")

Sets a secret and includes an client_request_token

>>> from aws_lambda_powertools.utilities import parameters
>>> import uuid
>>>
>>> parameters.set_secret(
        name="my-secret",
        value='{"password": "supers3cr3tllam@passw0rd"}',
        client_request_token=str(uuid.uuid4())
    )

https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/secretsmanager/client/put_secret_value.html
https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/secretsmanager/client/create_secret.html

Source code in aws_lambda_powertools/utilities/parameters/secrets.py

def set(
    self,
    name: str,
    value: str | bytes | dict,
    *,  # force keyword arguments
    client_request_token: str | None = None,
    **sdk_options,
) -> CreateSecretResponseTypeDef:
    """
    Modify the details of a secret or create a new secret if it doesn't already exist.

    We aim to minimize API calls by assuming that the secret already exists and needs updating.
    If it doesn't exist, we attempt to create a new one. Refer to the following workflow for a better understanding:


                      ┌────────────────────────┐      ┌─────────────────┐
            ┌───────▶│Resource NotFound error?│────▶│Create Secret API│─────┐
            │         └────────────────────────┘      └─────────────────┘     │
            │                                                                 │
            │                                                                 │
            │                                                                 ▼
    ┌─────────────────┐                                              ┌─────────────────────┐
    │Update Secret API│────────────────────────────────────────────▶│ Return or Exception │
    └─────────────────┘                                              └─────────────────────┘

    Parameters
    ----------
    name: str
        The ARN or name of the secret to add a new version to or create a new one.
    value: str, dict or bytes
        Specifies text data that you want to encrypt and store in this new version of the secret.
    client_request_token: str, optional
        This value helps ensure idempotency. It's recommended that you generate
        a UUID-type value to ensure uniqueness within the specified secret.
        This value becomes the VersionId of the new version. This field is
        auto-populated if not provided, but no idempotency will be enforced this way.
    sdk_options: dict, optional
        Dictionary of options that will be passed to the Secrets Manager update_secret API call

    Raises
    ------
    SetSecretError
        When attempting to update or create a secret fails.

    Returns:
    -------
    SetSecretResponse:
        The dict returned by boto3.

    Example
    -------
    **Sets a secret***

        >>> from aws_lambda_powertools.utilities import parameters
        >>>
        >>> parameters.set_secret(name="llamas-are-awesome", value="supers3cr3tllam@passw0rd")

    **Sets a secret and includes an client_request_token**

        >>> from aws_lambda_powertools.utilities import parameters
        >>> import uuid
        >>>
        >>> parameters.set_secret(
                name="my-secret",
                value='{"password": "supers3cr3tllam@passw0rd"}',
                client_request_token=str(uuid.uuid4())
            )

    URLs:
    -------
        https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/secretsmanager/client/put_secret_value.html
        https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/secretsmanager/client/create_secret.html
    """

    if isinstance(value, dict):
        value = json.dumps(value, cls=Encoder)

    if isinstance(value, bytes):
        sdk_options["SecretBinary"] = value
    else:
        sdk_options["SecretString"] = value

    if client_request_token:
        sdk_options["ClientRequestToken"] = client_request_token

    try:
        logger.debug(f"Attempting to update secret {name}")
        return self._update_secret(name=name, **sdk_options)
    except self.client.exceptions.ResourceNotFoundException:
        logger.debug(f"Secret {name} doesn't exist, creating a new one")
        return self._create_secret(name=name, **sdk_options)
    except Exception as exc:
        raise SetSecretError(f"Error setting secret - {str(exc)}") from exc

get_secret ¶

get_secret(name: str, transform: None = None, force_fetch: bool = False, max_age: int | None = None, **sdk_options) -> str

get_secret(name: str, transform: Literal['json'], force_fetch: bool = False, max_age: int | None = None, **sdk_options) -> dict

get_secret(name: str, transform: Literal['binary'], force_fetch: bool = False, max_age: int | None = None, **sdk_options) -> str | bytes | dict

get_secret(name: str, transform: Literal['auto'], force_fetch: bool = False, max_age: int | None = None, **sdk_options) -> bytes

get_secret(name: str, transform: TransformOptions = None, force_fetch: bool = False, max_age: int | None = None, **sdk_options) -> str | bytes | dict

Retrieve a parameter value from AWS Secrets Manager

PARAMETER	DESCRIPTION
`name`	Name of the parameter TYPE: `str`
`transform`	Transforms the content from a JSON object ('json') or base64 binary string ('binary') TYPE: `TransformOptions` DEFAULT: `None`
`force_fetch`	Force update even before a cached item has expired, defaults to False TYPE: `bool` DEFAULT: `False`
`max_age`	Maximum age of the cached value TYPE: `int \| None` DEFAULT: `None`
`sdk_options`	Dictionary of options that will be passed to the get_secret_value call DEFAULT: `{}`

RAISES	DESCRIPTION
`GetParameterError`	When the parameter provider fails to retrieve a parameter value for a given name.
`TransformParameterError`	When the parameter provider fails to transform a parameter value.

Example

Retrieves a secret*

>>> from aws_lambda_powertools.utilities.parameters import get_secret
>>>
>>> get_secret("my-secret")

Retrieves a secret and transforms using a JSON deserializer*

>>> from aws_lambda_powertools.utilities.parameters import get_secret
>>>
>>> get_secret("my-secret", transform="json")

Retrieves a secret and passes custom arguments to the SDK

>>> from aws_lambda_powertools.utilities.parameters import get_secret
>>>
>>> get_secret("my-secret", VersionId="f658cac0-98a5-41d9-b993-8a76a7799194")

Source code in aws_lambda_powertools/utilities/parameters/secrets.py

def get_secret(
    name: str,
    transform: TransformOptions = None,
    force_fetch: bool = False,
    max_age: int | None = None,
    **sdk_options,
) -> str | bytes | dict:
    """
    Retrieve a parameter value from AWS Secrets Manager

    Parameters
    ----------
    name: str
        Name of the parameter
    transform: str, optional
        Transforms the content from a JSON object ('json') or base64 binary string ('binary')
    force_fetch: bool, optional
        Force update even before a cached item has expired, defaults to False
    max_age: int, optional
        Maximum age of the cached value
    sdk_options: dict, optional
        Dictionary of options that will be passed to the get_secret_value call

    Raises
    ------
    GetParameterError
        When the parameter provider fails to retrieve a parameter value for
        a given name.
    TransformParameterError
        When the parameter provider fails to transform a parameter value.

    Example
    -------
    **Retrieves a secret***

        >>> from aws_lambda_powertools.utilities.parameters import get_secret
        >>>
        >>> get_secret("my-secret")

    **Retrieves a secret and transforms using a JSON deserializer***

        >>> from aws_lambda_powertools.utilities.parameters import get_secret
        >>>
        >>> get_secret("my-secret", transform="json")

    **Retrieves a secret and passes custom arguments to the SDK**

        >>> from aws_lambda_powertools.utilities.parameters import get_secret
        >>>
        >>> get_secret("my-secret", VersionId="f658cac0-98a5-41d9-b993-8a76a7799194")
    """

    # If max_age is not set, resolve it from the environment variable, defaulting to DEFAULT_MAX_AGE_SECS
    max_age = resolve_max_age(env=os.getenv(constants.PARAMETERS_MAX_AGE_ENV, DEFAULT_MAX_AGE_SECS), choice=max_age)

    # Only create the provider if this function is called at least once
    if "secrets" not in DEFAULT_PROVIDERS:
        DEFAULT_PROVIDERS["secrets"] = SecretsProvider()

    return DEFAULT_PROVIDERS["secrets"].get(
        name,
        max_age=max_age,
        transform=transform,
        force_fetch=force_fetch,
        **sdk_options,
    )

get_secrets_by_name ¶

get_secrets_by_name(names: list[str], transform: TransformOptions = None, force_fetch: bool = False, max_age: int | None = None, **sdk_options) -> dict[str, str | bytes | dict]

Retrieve multiple secrets by name from AWS Secrets Manager

PARAMETER	DESCRIPTION
`names`	List of secret names to retrieve TYPE: `list[str]`
`transform`	Transforms the content from a JSON object ('json') or base64 binary string ('binary') TYPE: `TransformOptions` DEFAULT: `None`
`force_fetch`	Force update even before a cached item has expired, defaults to False TYPE: `bool` DEFAULT: `False`
`max_age`	Maximum age of the cached value TYPE: `int \| None` DEFAULT: `None`
`sdk_options`	Dictionary of options that will be passed to the batch_get_secret_value call DEFAULT: `{}`

RAISES	DESCRIPTION
`GetParameterError`	When the parameter provider fails to retrieve secrets
`TransformParameterError`	When the parameter provider fails to transform a secret value

RETURNS	DESCRIPTION
`dict[str, str \| bytes \| dict]`	Dictionary mapping secret names to their values

Example

Retrieves multiple secrets

>>> from aws_lambda_powertools.utilities.parameters import get_secrets_by_name
>>>
>>> secrets = get_secrets_by_name(["db-password", "api-key", "jwt-secret"])
>>> print(secrets["db-password"])

Retrieves multiple secrets with JSON transformation

>>> from aws_lambda_powertools.utilities.parameters import get_secrets_by_name
>>>
>>> secrets = get_secrets_by_name(["config", "settings"], transform="json")
>>> print(secrets["config"]["database_url"])

Retrieves multiple secrets with additional filters

>>> from aws_lambda_powertools.utilities.parameters import get_secrets_by_name
>>>
>>> secrets = get_secrets_by_name(
...     names=["app-secret"],
...     Filters=[{"Key": "primary-region", "Values": ["us-east-1"]}]
... )

Source code in aws_lambda_powertools/utilities/parameters/secrets.py

def get_secrets_by_name(
    names: list[str],
    transform: TransformOptions = None,
    force_fetch: bool = False,
    max_age: int | None = None,
    **sdk_options,
) -> dict[str, str | bytes | dict]:
    """
    Retrieve multiple secrets by name from AWS Secrets Manager

    Parameters
    ----------
    names: list[str]
        List of secret names to retrieve
    transform: str, optional
        Transforms the content from a JSON object ('json') or base64 binary string ('binary')
    force_fetch: bool, optional
        Force update even before a cached item has expired, defaults to False
    max_age: int, optional
        Maximum age of the cached value
    sdk_options: dict, optional
        Dictionary of options that will be passed to the batch_get_secret_value call

    Raises
    ------
    GetParameterError
        When the parameter provider fails to retrieve secrets
    TransformParameterError
        When the parameter provider fails to transform a secret value

    Returns
    -------
    dict[str, str | bytes | dict]
        Dictionary mapping secret names to their values

    Example
    -------
    **Retrieves multiple secrets**

        >>> from aws_lambda_powertools.utilities.parameters import get_secrets_by_name
        >>>
        >>> secrets = get_secrets_by_name(["db-password", "api-key", "jwt-secret"])
        >>> print(secrets["db-password"])

    **Retrieves multiple secrets with JSON transformation**

        >>> from aws_lambda_powertools.utilities.parameters import get_secrets_by_name
        >>>
        >>> secrets = get_secrets_by_name(["config", "settings"], transform="json")
        >>> print(secrets["config"]["database_url"])

    **Retrieves multiple secrets with additional filters**

        >>> from aws_lambda_powertools.utilities.parameters import get_secrets_by_name
        >>>
        >>> secrets = get_secrets_by_name(
        ...     names=["app-secret"],
        ...     Filters=[{"Key": "primary-region", "Values": ["us-east-1"]}]
        ... )
    """
    if not names:
        raise GetSecretError("You must provide at least one secret name")

    # If max_age is not set, resolve it from the environment variable, defaulting to DEFAULT_MAX_AGE_SECS
    max_age = resolve_max_age(env=os.getenv(constants.PARAMETERS_MAX_AGE_ENV, DEFAULT_MAX_AGE_SECS), choice=max_age)

    # Only create the provider if this function is called at least once
    if "secrets" not in DEFAULT_PROVIDERS:
        DEFAULT_PROVIDERS["secrets"] = SecretsProvider()

    return DEFAULT_PROVIDERS["secrets"].get_multiple(
        names=names,
        max_age=max_age,
        transform=transform,
        force_fetch=force_fetch,
        **sdk_options,
    )

set_secret ¶

set_secret(name: str, value: str | bytes, *, client_request_token: str | None = None, **sdk_options) -> CreateSecretResponseTypeDef

Modify the details of a secret or create a new secret if it doesn't already exist.

We aim to minimize API calls by assuming that the secret already exists and needs updating. If it doesn't exist, we attempt to create a new one. Refer to the following workflow for a better understanding:

              ┌────────────────────────┐      ┌─────────────────┐
    ┌───────▶│Resource NotFound error?│────▶│Create Secret API│─────┐
    │         └────────────────────────┘      └─────────────────┘     │
    │                                                                 │
    │                                                                 │
    │                                                                 ▼

┌─────────────────┐ ┌─────────────────────┐ │Update Secret API│────────────────────────────────────────────▶│ Return or Exception │ └─────────────────┘ └─────────────────────┘

PARAMETER	DESCRIPTION
`name`	The ARN or name of the secret to add a new version to or create a new one. TYPE: `str`
`value`	Specifies text data that you want to encrypt and store in this new version of the secret. TYPE: `str \| bytes`
`client_request_token`	This value helps ensure idempotency. It's recommended that you generate a UUID-type value to ensure uniqueness within the specified secret. This value becomes the VersionId of the new version. This field is auto-populated if not provided, but no idempotency will be enforced this way. TYPE: `str \| None` DEFAULT: `None`
`sdk_options`	Dictionary of options that will be passed to the Secrets Manager update_secret API call DEFAULT: `{}`

RAISES	DESCRIPTION
`SetSecretError`	When attempting to update or create a secret fails.

Example

Sets a secret*

>>> from aws_lambda_powertools.utilities import parameters
>>>
>>> parameters.set_secret(name="llamas-are-awesome", value="supers3cr3tllam@passw0rd")

Sets a secret and includes an client_request_token

>>> from aws_lambda_powertools.utilities import parameters
>>>
>>> parameters.set_secret(
        name="my-secret",
        value='{"password": "supers3cr3tllam@passw0rd"}',
        client_request_token="YOUR_TOKEN_HERE"
    )

https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/secretsmanager/client/put_secret_value.html
https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/secretsmanager/client/create_secret.html

Source code in aws_lambda_powertools/utilities/parameters/secrets.py

def set_secret(
    name: str,
    value: str | bytes,
    *,  # force keyword arguments
    client_request_token: str | None = None,
    **sdk_options,
) -> CreateSecretResponseTypeDef:
    """
    Modify the details of a secret or create a new secret if it doesn't already exist.

    We aim to minimize API calls by assuming that the secret already exists and needs updating.
    If it doesn't exist, we attempt to create a new one. Refer to the following workflow for a better understanding:


                      ┌────────────────────────┐      ┌─────────────────┐
            ┌───────▶│Resource NotFound error?│────▶│Create Secret API│─────┐
            │         └────────────────────────┘      └─────────────────┘     │
            │                                                                 │
            │                                                                 │
            │                                                                 ▼
    ┌─────────────────┐                                              ┌─────────────────────┐
    │Update Secret API│────────────────────────────────────────────▶│ Return or Exception │
    └─────────────────┘                                              └─────────────────────┘

    Parameters
    ----------
    name: str
        The ARN or name of the secret to add a new version to or create a new one.
    value: str, dict or bytes
        Specifies text data that you want to encrypt and store in this new version of the secret.
    client_request_token: str, optional
        This value helps ensure idempotency. It's recommended that you generate
        a UUID-type value to ensure uniqueness within the specified secret.
        This value becomes the VersionId of the new version. This field is
        auto-populated if not provided, but no idempotency will be enforced this way.
    sdk_options: dict, optional
        Dictionary of options that will be passed to the Secrets Manager update_secret API call

    Raises
    ------
    SetSecretError
        When attempting to update or create a secret fails.

    Returns:
    -------
    SetSecretResponse:
        The dict returned by boto3.

    Example
    -------
    **Sets a secret***

        >>> from aws_lambda_powertools.utilities import parameters
        >>>
        >>> parameters.set_secret(name="llamas-are-awesome", value="supers3cr3tllam@passw0rd")

    **Sets a secret and includes an client_request_token**

        >>> from aws_lambda_powertools.utilities import parameters
        >>>
        >>> parameters.set_secret(
                name="my-secret",
                value='{"password": "supers3cr3tllam@passw0rd"}',
                client_request_token="YOUR_TOKEN_HERE"
            )

    URLs:
    -------
        https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/secretsmanager/client/put_secret_value.html
        https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/secretsmanager/client/create_secret.html
    """

    # Only create the provider if this function is called at least once
    if "secrets" not in DEFAULT_PROVIDERS:
        DEFAULT_PROVIDERS["secrets"] = SecretsProvider()

    return DEFAULT_PROVIDERS["secrets"].set(
        name=name,
        value=value,
        client_request_token=client_request_token,
        **sdk_options,
    )