Signing Requests

Amazon API Gateway requires that you authenticate every request you send by signing the request. To sign a request, you calculate a digital signature using a cryptographic hash function, which returns a hash value based on the input. The input includes the text of your request and your secret access key. The hash function returns a hash value that you include in the request as your signature. The signature is part of the Authorization header of your request.

After receiving your request, Amazon API Gateway recalculates the signature using the same hash function and input that you used to sign the request. If the resulting signature matches the signature in the request, Amazon API Gateway processes the request. Otherwise, the request is rejected.

Amazon API Gateway supports authentication using AWS Signature Version 4. The process for calculating a signature can be broken into three tasks:

Create a Canonical Request

Follow the discussions in Task 1: Create a Canonical Request For Signing AWS API Requests to create your HTTP request in canonical format. The canonical request must include the host and x-amz-date headers for requests without a payload, such as GET or DELETE and must also include the content-type header for requests requiring a payload, such as PATCH, POST or PUT.

Create a String to Sign

Follow the instructions in Task 2: Create a String to Sign for Signing AWS API Requests to create a string as one of the input values to your cryptographic hash function. The string, called the string to sign, is a concatenation of the name of the hash algorithm, the request date, a credential scope string, and the canonical request from the previous task. The credential scope string itself is a concatenation of date, region, and service information.

For the Credential parameter, specify:

- The code for the endpoint to which you're sending the request, for example, `us-east-1`. For a list of regions and endpoints for Amazon API Gateway, see the <a href="http://docs.aws.amazon.com/general/latest/gr/rande.html" target="_blank">Regions and Endpoints</a> chapter of the *Amazon Web Services General Reference*. When specifying the code for the endpoint, include only the part between `apigateway.` and `.amazonaws.com`
- apigateway for the service abbreviation

For the SignedHeader parameter, specify:

- `host;x-amz-date` for requests without payloads.
- `content-type;host;x-amz-date` for requests with payloads.

For example:

Credential=AKIAIOSFODNN7EXAMPLE/20130501/us-east-1/apigateway/aws4_request, SignedHeader=host;x-amz-date

Calculate the Signature

Follow the instructions in Task 3: Calculate the Signature for Signing AWS API Requests to create a signature for your request by using a cryptographic hash function that accepts two input strings: the string to sign and a derived key. The derived key is calculated by starting with your secret access key and using the credential scope string to create a series of hash-based message authentication codes (HMACs).

Add the Authorization Header to the Request

Follow the instructions given in Task 4: Add the Authorization Header to the AWS API Requests to construct the Authorization header value using the canonical request, string to sign, and signature, derived in the above steps and attach the header to the request.