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

Short description

API 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.

Resolution

IAM authentication

Make 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 credentials

Verify 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 mismatch

If 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 string
content-type:application/json                            -------- header key-value pair. One header per line
host: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 headers
d167e99c53f15b0c105101d468ae35a3dc9187839ca081095e340f3649a04501        -------- hash of the payload

Example 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=host
host:iam.amazonaws.com

host
<hashed-value>'

The String-to-Sign should have been
'AWS4-HMAC-SHA256
20120223T063000Z
20120223/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 header

Make 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-signature

If 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 information

Code examples in the AWS SDKs

How do I troubleshoot HTTP 403 errors from API Gateway?