Signing Amazon API requests - Amazon General Reference
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China.

Signing Amazon API requests

Important

The Amazon SDKs, Amazon Command Line Interface (Amazon CLI), and other Amazon tools sign API requests for you using the access key that you specify when you configure the tool. When you use these tools, you don’t need to learn how to sign API requests. The following documentation explains how to sign API requests, but is only useful if you’re writing your own code to send and sign Amazon API requests. We recommend that you use the Amazon SDKs or other Amazon tools to send API requests, instead of writing your own code.

When you send API requests to Amazon, you sign the requests so that Amazon can identify who sent them. You sign requests with your Amazon access key, which consists of an access key ID and secret access key. Some requests don’t need to be signed, including anonymous requests to Amazon Simple Storage Service (Amazon S3) and some API operations in Amazon Security Token Service (Amazon STS) such as AssumeRoleWithWebIdentity.

When to sign requests

When you write custom code to send API requests to Amazon, you need to include code to sign the requests. You might do this for the following reasons:

  • You are working with a programming language for which there is no Amazon SDK.

  • You want complete control over how a request is sent to Amazon.

You don’t need to sign requests when you use the Amazon CLI or one of the Amazon SDKs. These tools calculate the signature for you, and also manage the connection details, handle request retries, and provide error handling. In most cases, they also contain sample code, tutorials, and other resources to help you get started writing applications that interact with Amazon.

Why requests are signed

The signing process helps secure requests in the following ways:

  • Verify the identity of the requester

    Signing makes sure that the request has been sent by someone with a valid access key. For more information, see Understanding and getting your Amazon credentials.

  • Protect data in transit

    To prevent tampering with a request while it's in transit, some of the request elements are used to calculate a hash (digest) of the request, and the resulting hash value is included as part of the request. When an Amazon service receives the request, it uses the same information to calculate a hash and matches it against the hash value in your request. If the values don't match, Amazon denies the request.

  • Protect against potential replay attacks

    In most cases, a request must reach Amazon within five minutes of the time stamp in the request. Otherwise, Amazon denies the request.

Signing requests

To sign a request, you first calculate a hash (digest) of the request. Then you use the hash value, some other information from the request, and your secret access key to calculate another hash known as the signature. Then you add the signature to the request in one of the following ways:

  • Using the HTTP Authorization header.

  • Adding a query string value to the request. Because the signature is part of the URL in this case, this type of URL is called a presigned URL.

Signature versions

Amazon supports Signature Version 4 (SigV4) and Signature Version 2 (SigV2). All Amazon services in all Amazon Web Services Regions support SigV4, except Amazon SimpleDB which requires SigV2. The Amazon SDKs, including the Amazon CLI, automatically use SigV4 for all services that support it. If you manually sign API requests, you should do the same.

Amazon is rolling out an extension to SigV4 called Signature Version 4A (SigV4A). This extension enables signatures that are valid in more than one Amazon Web Services Region. This is required for signing multi-Region API requests, for example with Amazon S3 Multi-Region Access Points. The Amazon SDKs and Amazon CLI support SigV4A and use it automatically when it’s needed.

Note

To use SigV4A with temporary security credentials—for example, when using IAM roles—make sure that you request the temporary credentials from a regional endpoint in Amazon Security Token Service (Amazon STS). Don’t use the global endpoint for Amazon STS (sts.amazonaws.com), because by default temporary credentials from the global endpoint don’t work with SigV4A. You can use any of the regional endpoints for Amazon STS.