AWS Lambda Base64 Encoded Request Body/Response Body
Table of Contents
When working with AWS Lambda, you may encounter scenarios where the request body appears as a base64 encoded string with an isBase64Encoded flag. While most guides focus on decoding the request body within your Lambda function, this post examines why this encoding happens in the first place.
Some guides suggest setting */* in the binary media type configuration in API Gateway to handle all media types without warnings, including the AWS documentation. However, it’s crucial to understand that API Gateway’s binary media types setting does more than just convert base64 strings to binary in responses—it also determines when request bodies are converted to base64 strings.
Example repo
You can clone the example repository and deploy it to your AWS account to test the lambda function.
- POST /input API: Logs the JSON stringified event object in CloudWatch. Send JSON or form-data while manually setting the Content-Type request header to
application/octet-streamorimage/jpegto observe the base64 encoded request body. Send JSON or form-data requests without changing the Content-Type header to see the normal request body. - GET /image API: Set the Accept request header to
image/jpegto receive the decoded image or*/*to receive the base64 encoded string.
Encoded Request Body
Request body encoding is determined by two key factors: the binary media type configuration in API Gateway and the Content-Type request header.
In this example, I’ve configured application/octet-stream and image/jpeg as binary media types in API Gateway. When the Content-Type request header matches one of these types (application/octet-stream or image/jpeg), API Gateway will encode the request body to base64. If the Content-Type doesn’t match, the request body remains in its original format as sent by the client.
Important consideration: Most API designs accept JSON request bodies or form-data. If you add application/json or application/x-www-form-urlencoded to the binary media type configuration, these request bodies will be base64-encoded even when clients aren’t sending files.
For wildcard patterns like application/* in the binary media type setting, API Gateway matches any Content-Type header starting with application/. This means using application/* will convert request bodies with Content-Type headers like application/x-www-form-urlencoded, application/json, application/pdf, etc., to base64 strings.
Using */* in the binary media type setting is strongly discouraged because it matches any Content-Type, causing all request bodies to be base64-encoded.
Note: When the Content-Type header is missing from a request, API Gateway defaults to JSON format and uses application/json for matching purposes.
Encoded Response Body
Converting base64 strings to binary in responses is determined by two factors: the binary media type configuration in API Gateway and the Accept request header from the client.
With application/octet-stream and image/jpeg configured as binary media types, API Gateway will convert the response body from base64 to binary under specific conditions:
- The first value of the Accept request header matches a configured binary media type (
application/octet-streamorimage/jpeg) - The Lambda response payload includes the
isBase64Encoded: trueflag
For wildcard patterns like application/* in the binary media type setting, API Gateway matches Accept headers starting with application/. This means using application/* will convert base64-encoded response bodies to binary when the Accept header is set to application/json, application/pdf, etc.
However, if you explicitly configure a specific type like application/octet-stream in the API Gateway binary media type setting but set the Accept request header to a wildcard like application/*, the base64 string will not be converted back to binary before being sent to the client. This occurs because wildcards in the Accept header don’t match explicit types in the binary media type configuration.
When the Accept request header accepts multiple media types, API Gateway only considers the first media type in the header. For example, if you’ve added application/octet-stream to the binary media type configuration but set the Accept header to application/*, application/octet-stream, the response body will remain as a base64 string and won’t be converted back to binary, because API Gateway only evaluates the first value (application/*).