Question: How can I troubleshoot signature mismatch errors when making SigV4 signed requests with IAM authentication to API Gateway?

The Signature Version 4 (SigV4) signed request to Amazon API Gateway failed with a 403 response and an error. The error is similar to the following: "The request signature we calculated does not match the signature you provided. Check your AWS Secret Access Key and signing method."Short descriptionAPI Gateway API endpoints using AWS Identity and Access Management (IAM) authentication might return 403 errors if:The API request isn't signed and the API request uses IAM authentication.The IAM credentials used to sign the request are incorrect or don't have permissions to invoke the API.The signature of the signed API request doesn't match the signature for the API Gateway API endpoint.The API request header is incorrect.

ResolutionIAM authenticationMake sure that the API request using IAM authentication is signed with SigV4. If the API request isn't signed, then you might receive the following error: "Missing Authentication Token."IAM credentialsVerify that the authentication credentials for the access key and secret key are correct. If the access key is incorrect, then you might receive the following error: "The security token included in the request is invalid."Make sure that the IAM entity used to sign the request has execute-api:Invoke permissions. If the IAM entity doesn't have execute-api:Invoke permissions, then you might receive the following error: "User: arn:aws:iam::xxxxxxxxxxxx:user/username is not authorized to perform: execute-api:Invoke on resource"Signature mismatchIf the secret access key is incorrect, then you might receive the following error: "The request signature we calculated does not match the signature you provided."The secret access key must match the access key ID in the Credential parameter. For instructions, follow the Send a request to test the authentication settings section in How do I activate IAM authentication for API Gateway REST APIs?Make sure that you followed the instructions for the SigV4 signing process. If any values in the signature calculation are incorrect, then you might receive the following error: "The request signature we calculated does not match the signature you provided."When API Gateway receives a signed request, it recalculates the signature. If there are differences in the values, then API Gateway gets a different signature. Compare the canonical request and string to your signed request with the value in the error message. Modify the signing process if there are any differences.Example canonical request:GET                                                      -------- HTTP method/                                                        -------- Path. For API stage endpoint, it should be /{stage-name}/{resource-path}                                                         -------- Query string key-value pair. Leave it blank if the request doesn't have any query stringcontent-type:application/json                            -------- header key-value pair. One header per linehost:0123456789.execute-api.us-east-1.amazonaws.com      -------- host and x-amz-date are required headers for all signed request                       x-amz-date:20220806T024003Z                              content-type;host;x-amz-date                             -------- A list of signed headersd167e99c53f15b0c105101d468ae35a3dc9187839ca081095e340f3649a04501        -------- hash of the payloadExample canonical error response:<ErrorResponse xmlns="https://iam.amazonaws.com/doc/2010-05-08/">  <Error>    <Type>Sender</Type>    <Code>SignatureDoesNotMatch</Code>    <Message>The request signature we calculated does not match the signature you provided. Check your AWS Secret Access Key and signing method. Consult the service documentation for details.The canonical string for this request should have been 'GET / Action=ListGroupsForUser&MaxItems=100&UserName=Test&Version=2010-05-08&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAIOSFODNN7EXAMPLE%2F20120223%2Fus-east-1%2Fiam%2Faws4_request&X-Amz-Date=20120223T063000Z&X-Amz-SignedHeaders=hosthost:iam.amazonaws.comhost<hashed-value>'The String-to-Sign should have been'AWS4-HMAC-SHA25620120223T063000Z20120223/us-east-1/iam/aws4_request<hashed-value>'</Message>  </Error>  <RequestId>4ced6e96-5de8-11e1-aa78-a56908bdf8eb</RequestId></ErrorResponse>Note: For API gateway headers, only the host and x-amz-date headers are required.API request headerMake sure that the SigV4 authorization header includes the correct credential key similar to the following:Authorization: AWS4-HMAC-SHA256 Credential=AKIAIOSFODNN7EXAMPLE/20130524/us-east-1/s3/aws4_request, SignedHeaders=host;range;x-amz-date,Signature=example-generated-signatureIf the credential key is missing or incorrect, you might receive the following error: "Authorization header requires 'Credential' parameter. Authorization header requires 'Signature' parameter."Make sure that the SigV4 authorization request also includes the request date using either HTTP Date or the x-amz-date header.

Related informationCode examples in the AWS SDKsHow do I troubleshoot HTTP 403 errors from API Gateway?