Troubleshoot signed requests for AWS APIs

When you develop code that creates a signed request, you might receive HTTP 403 SignatureDoesNotMatch from AWS services. These errors mean that the signature value in your HTTP request to AWS did not match the signature that the AWS service calculated. HTTP 401 Unauthorized errors return when permissions do not allow the caller to make the request.

API requests might return an error if:

Credential errors

Make sure that the API request is signed with SigV4. If the API request isn't signed, then you might receive the error: Missing Authentication Token. Add the missing signature and resend the request.

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 error: Unauthorized. Make sure the entity used to sign the request is authorized to make the request. For details, see Troubleshooting access denied error messages.

Canonical request and signing string errors

If you incorrectly calculated the canonical request in Step 2: Create a hash of the canonical request or Step 3: Create a string to sign, the signature verification step performed by the service fails with the error message:

The request signature we calculated does not match the signature you provided

When the AWS service receives a signed request, it recalculates the signature. If there are differences in the values, then the signatures don’t match. 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.

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 a 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 requests.                       
x-amz-date:20220806T024003Z                              

content-type;host;x-amz-date                             -------- A list of signed headers
d167e99c53f15b0c105101d468ae35a3dc9187839ca081095e340f3649a04501        -------- Hash of the payload

To verify that the secret key matches the access key ID, you can test them with a known working implementation. For example, use an AWS SDK or the AWS CLI to make a request to AWS.

API request header

Make sure that the SigV4 authorization header you added in Step 4: Calculate the signature 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 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.

Credential scope errors

The credential scope you created in Step 3: Create a string to sign restricts a signature to a specific date, Region, and service. This string has the following format:

YYYYMMDD/region/service/aws4_request

Date

If the credential scope does not specify the same date as the x-amz-date header, the signature verification step fails with the following error message:

Date in Credential scope does not match YYYYMMDD from ISO-8601 version of date from HTTP

If the request specifies a time in the future, the signature verification step fails with the following error message:

Signature not yet current: date is still later than date

If the request has expired, the signature verification step fails with the following error message:

Signature expired: date is now earlier than date

Region

If the credential scope does not specify the same Region as the request, the signature verification step fails with the following error message:

Credential should be scoped to a valid Region, not region-code

Service

If the credential scope does not specify the same service as the host header, the signature verification step fails with the following error message:

Credential should be scoped to correct service: 'service'

Termination string

If the credential scope does not end with aws4_request, the signature verification step fails with the following error message:

Credential should be scoped with a valid terminator: 'aws4_request'

Key signing errors

Errors that are caused by incorrect derivation of the signing key or improper use of cryptography are more difficult to troubleshoot. After you verify that the canonical string and the string to sign are correct, you can also check for one of the following issues:

To verify that the secret key matches the access key ID, you can test them with a known working implementation. For example, use an AWS SDK or the AWS CLI to make a request to AWS. For examples, see Request signature examples