DataDog · litianningdatadog · May 6, 2026 · May 6, 2026 · May 6, 2026 · estherk15
@@ -49,6 +49,7 @@
 - [Visualize and model AWS services correctly](#visualize-and-model-aws-services-by-resource-name)
 - [Send logs to Observability Pipelines](#send-logs-to-observability-pipelines)
 - [Reload API key secret periodically](#reload-api-key-secret-periodically)
+- [Store API key in AWS Secrets Manager](#store-api-key-in-aws-secrets-manager)
 - [Troubleshoot](#troubleshoot)
 - [Further Reading](#further-reading)
 
@@ -799,6 +800,18 @@
 
 This is available for version 88+ of the Datadog Lambda Extension.
 
+## Store API key in AWS Secrets Manager
-## Store API key in AWS Secrets Manager
+## Store the API key in AWS Secrets Manager
-## Store API key in AWS Secrets Manager
+## Store the API key in AWS Secrets Manager
+
+`DD_API_KEY_SECRET_ARN` specifies the ARN of an AWS Secrets Manager secret that stores your Datadog API key. When set, the Datadog Lambda Extension fetches the secret at cold start and uses its value as the API key. The Lambda function's execution role must be granted secretsmanager:GetSecretValue permission on the referenced ARN.
-`DD_API_KEY_SECRET_ARN` specifies the ARN of an AWS Secrets Manager secret that stores your Datadog API key. When set, the Datadog Lambda Extension fetches the secret at cold start and uses its value as the API key. The Lambda function's execution role must be granted secretsmanager:GetSecretValue permission on the referenced ARN.
+`DD_API_KEY_SECRET_ARN` specifies the ARN of an AWS Secrets Manager secret that stores your Datadog API key. When set, the Datadog Lambda Extension fetches the secret at cold start and uses its value as the API key. Grant the Lambda function's execution role `secretsmanager:GetSecretValue` permission on the referenced ARN.
-`DD_API_KEY_SECRET_ARN` specifies the ARN of an AWS Secrets Manager secret that stores your Datadog API key. When set, the Datadog Lambda Extension fetches the secret at cold start and uses its value as the API key. The Lambda function's execution role must be granted secretsmanager:GetSecretValue permission on the referenced ARN.
+`DD_API_KEY_SECRET_ARN` specifies the ARN of an AWS Secrets Manager secret that stores your Datadog API key. When set, the Datadog Lambda Extension fetches the secret at cold start and uses its value as the API key. Grant the Lambda function's execution role `secretsmanager:GetSecretValue` permission on the referenced ARN.
+
+Starting v96, the secret value can be stored in either of two formats:
-Starting v96, the secret value can be stored in either of two formats:
+Starting with version 96, you can store the secret value in one of the following formats:
-Starting v96, the secret value can be stored in either of two formats:
+Starting with version 96, you can store the secret value in one of the following formats:
+- Plain string: the secret value is used directly as the API key.
+- JSON object: if the secret value parses as a JSON object containing a `dd_api_key` field, the value of that field is extracted and used as the API key. This is convenient when the same secret stores multiple credentials (for example, alongside an app key or other tokens).
- Plain string: the secret value is used directly as the API key.
- JSON object: if the secret value parses as a JSON object containing a `dd_api_key` field, the value of that field is extracted and used as the API key. This is convenient when the same secret stores multiple credentials (for example, alongside an app key or other tokens).
+- **Plain string**: The extension uses the secret value as the API key.
+- **JSON object**: If the secret value parses as a JSON object containing a `dd_api_key` field, the extension extracts that field's value and uses it as the API key. This is useful when the same secret stores multiple credentials (for example, alongside an app key or other tokens).
- Plain string: the secret value is used directly as the API key.
- JSON object: if the secret value parses as a JSON object containing a `dd_api_key` field, the value of that field is extracted and used as the API key. This is convenient when the same secret stores multiple credentials (for example, alongside an app key or other tokens).
+- **Plain string**: The extension uses the secret value as the API key.
+- **JSON object**: If the secret value parses as a JSON object containing a `dd_api_key` field, the extension extracts that field's value and uses it as the API key. This is useful when the same secret stores multiple credentials (for example, alongside an app key or other tokens).
+```sh
+  { "dd_api_key": "<YOUR_DATADOG_API_KEY>" }
+```
-```sh
-  { "dd_api_key": "<YOUR_DATADOG_API_KEY>" }
-```
+```json
+{ "dd_api_key": "<YOUR_DATADOG_API_KEY>" }
+```
-```sh
-  { "dd_api_key": "<YOUR_DATADOG_API_KEY>" }
-```
+```json
+{ "dd_api_key": "<YOUR_DATADOG_API_KEY>" }
+```
+Attention: If the JSON object does not contain a `dd_api_key` field, or the value is not valid JSON, the extension falls back to using the raw secret string. The JSON key name is fixed as dd_api_key and is not configurable.
-Attention: If the JSON object does not contain a `dd_api_key` field, or the value is not valid JSON, the extension falls back to using the raw secret string. The JSON key name is fixed as dd_api_key and is not configurable.
+**Note**: If the JSON object does not contain a `dd_api_key` field, or the value is not valid JSON, the extension falls back to using the raw secret string. The JSON key name is fixed as `dd_api_key` and is not configurable.
-Attention: If the JSON object does not contain a `dd_api_key` field, or the value is not valid JSON, the extension falls back to using the raw secret string. The JSON key name is fixed as dd_api_key and is not configurable.
+**Note**: If the JSON object does not contain a `dd_api_key` field, or the value is not valid JSON, the extension falls back to using the raw secret string. The JSON key name is fixed as `dd_api_key` and is not configurable.
+
 ## Troubleshoot
 
 If you have trouble configuring your installations, set the environment variable `DD_LOG_LEVEL` to `debug` for debugging logs. For additional troubleshooting tips, see the [serverless monitoring troubleshooting guide][39].