Sign In
Sign In

Onboarding Process - Security Systems

On this page we'll take you though the steps to use AWS Signature Version 4, which is used to sign the requests that are sent to the Amazon Gift Card On Demand (AGCOD) service.

AWS Signature Version 4 Sample code

Signature Version 4 is an AWS standard. AWS documentation includes code snippets that can call an operation using this signature. The following table shows parameters you can modify in the Python POST example found at Examples of the Complete Version 4 Signing Process. With these modifications, the Python code calls the CreateGiftCard operation in the North America Sandbox using a JSON body:

parameter value
service AGCODService
host agcod-v2-gamma.amazon.com
region us-east-1
endpoint https://agcod-v2-gamma.amazon.com/CreateGiftCard
content_type application/json
amz_target com.amazonaws.agcod.AGCODService.CreateGiftCard
request_parameters Copy body from a request made in Incentives API Scratchpad that uses a JSON body
access_key, secret_key Provide your keys
canonical_url /CreateGiftCard

↑ Back to top

Also find additional snippets in Java, C#, Python, Ruby, and JavaScript: Examples of How to Derive a Signing Key for Signature Version 4

Implementing Signature Version 4

The code samples listed in our API services page might not cover your exact scenario. To implement Signature Version 4 from scratch, start by studying these topics:

Every REST operation request your code sends must include a signature. To sign a request, you create a string that includes the text of your request along with your secret access key. You pass this string to a cryptographic hash function, which returns a hash value. You include this hash value in the Signature field of the Authorization header of your REST operation request. Before handling your request, our services recalculate the signature using the same inputs, and confirm your Authorization hash value matches our own calculation.

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

Task 1: Create a Canonical Request

Create your HTTP request the canonical format described in Task 1: Create a Canonical Request for Signature Version 4 in the Amazon Web Services General Reference.

Task 2: Create a String to Sign

Create a string that you will use 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 x-amz-credential parameter, specify the code for the endpoint where you will send the request, for example, us-east-1. Find your region in the Endpoints tables. Example:

x-amz-credential=AKIAIGHKAVYIDBOH3O3A/20170118/us-east-1/AGCODService/aws4_request

The x-amz-credential header is used when authentication parameters are added to the query string. They are as easily added to the single Authorization header, and in that instance, x-amz-credential does not appear. So it's a bit confusing to mention x-amz-credential, a keyword that is only used in a particular instance, and isn't required. Its value is required, but the x-amz-credential is only required when query string parameters are used to carry authentication.

Task 3: Create a Signature

Create a signature for your request by using a cryptographic hash function that accepts two input strings: your 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). The following diagram illustrates the general process of computing a signature:

Signed Request Example

Payload to sign

{
  "loadBalanceRequestId": "Amazon123456",
  "partnerId": "Amazon",
  "amount": {
    "currencyCode": "USD",
    "value": "1000"
  },
  "transactionSource": {
    "sourceId": "Customer Service"
  },
  "account": {
    "id": "amz1.account.123512341234",
    "type": "2"
  }
}

Hashed Payload

24921f8ae68d62e1d96fd98e33f28da3e52826f43c5fa0389bfa33817e2711a1

Canonical request (include empty lines)

POST /LoadAmazonBalance

accept: application/json
content-type: application/json
host: agcod-v2-gamma.amazon.com
x-amz-date: 20160708T073147Z
x-amz-target: com.amazonaws.agcod.AGCODService.LoadAmazonBalance

accept;content-type;host;x-amz-date;x-amz-target 24921f8ae68d62e1d96fd98e33f28da3e52826f43c5fa0389bfa33817e2711a1

Hashed Canonical request

a6a2e4283152cbcc7114409dfbc3dda721663f4bb14b6e34f8e1f71c374f9c14

String to sign

AWS4-HMAC-SHA256
20160708T073147Z
20160708/us-east-1/AGCODService/aws4_request
a6a2e4283152cbcc7114409dfbc3dda721663f4bb14b6e34f8e1f71c374f9c14

Derived signing key

780860beb9efce461eaee56c38d7f904cf1b803cd9ea6f2c3402415b92af9453

Signature

Your signature will be different, because you have different security access key credentials, but will follow this format:

66bd6a9ee258bcc34b7c0084ef871f2cb734e579b26f62ffce3ca1a33c06074a

Signed payload

POST /LoadAmazonBalance HTTP/1.1
accept:application/json
content-type:application/json
host:agcod-v2-gamma.amazon.com
x-amz-date:20160708T073147Z
x-amz-target:com.amazonaws.agcod.AGCODService.LoadAmazonBalance
Authorization:AWS4-HMAC-SHA256 Credential=<AWS Key Id used for signing>/20160708/useast-1/AGCODService/aws4_request, SignedHeaders=accept;content-type;host;x-amz-date;x-amz-target, Signature=66bd6a9ee258bcc34b7c0084ef871f2cb734e579b26f62ffce3ca1a33c06074a
{
  "loadBalanceRequestId": "Amazon123456",
  "partnerId": "Amazon",
  "amount": {
    "currencyCode": "USD",
    "value": "1000"
  },
  "transactionSource": {
    "sourceId": "Customer Service"
  },
  "account": {
    "id": "amz1.account.123512341234",
    "type": "2"
  }
}

↑ Back to top

Troubleshooting your signature signing code

Check the following common coding errors at Examples of How to Derive a Signing Key for Signature Version 4.

Common coding errors include:

  • Inadvertently swapping the key and the data when calculating intermediary keys. The result of the previous step's computation is the key, not the data. Check the documentation for your cryptographic primitives carefully to ensure that you place the parameters in the proper order.
  • Forgetting to prepend the string "AWS" in front of the key for the first step. It is possible to implement the key derivation using a “for loop” or iterator. When you do, do not forget to special-case the first iteration so that it includes the "AWS" string.
  • Forgetting to use the asBytes option for the JavaScript HMAC.Crypto function. If you do not use the asBytes option, the HMAC implementation will perform an additional hex encoding by default.
  • Make sure the query string in your request is both properly sorted and encoded, the header names have been converted to lowercase characters and the headers have been sorted by character code. See Create a Canonical Request for Signature Version 4.
  • For JSON body requests, only content_type set to application/json will succeed.

↑ Back to top

Secure Data Transmission

Incentives API endpoints are open only through a secure port (HTTPS) and all traffic over this channel is secured using SSL/TLS 1.2. This industry standard protocol encrypts gift card data while in transit. You are required to provide your own secure mechanisms within your systems to prevent unauthorized access to encryption keys used by SSL/TLS 1.2.

↑ Back to top

Handling Keys

Access keys are credentials you use to sign your programmatic requests to any Incentives API endpoint. Like a user name and password, you must use both the access key ID and secret access key together to authenticate all your requests.

A partner account that has administrator permissions can new access keys and control existing keys from within the Incentives API Portal, on the API security credentials page. (A partner account that does not have administrator permissions cannot see this page. You can ask us to give an account administrator access by emailing us at incentives-api@giftcards.amazon.com.)

Security for credentials

The access keys and secret keys provided on the API security credentials page must be secured from unauthorized access and accidental release. This is true for both production and sandbox credentials. Security of your system and your funds relies on secure handling of these secrets. Do not share your keys.

Rotating keys

Changing access keys on a regular schedule is a well-known security best practice that reduces the business impact of a compromised key. As a security best practice, we recommend that you regularly rotate (change) your access keys. Performing an established process regularly also ensures the operational steps around key rotation are verified, so changing a key is never a scary step for your organization.

You should change your access keys at least once every 90 days (3 months). You will receive an email 30 days before the keys should be rotated as a reminder to initiate the process. If you have questions please contact your account manager or incentives-api@giftcards.amazon.com.

To rotate access keys, follow these steps:

  1. In the Incentives API portal, click API security credentials.
  2. Click Create new access key.
  3. Update all your applications to use the new access key.
  4. Confirm that all requests to Incentives API operations are succeeding using the new key values.
  5. For the original key, click Deactivate.
  6. Confirm again that all requests to Incentives API operations are succeeding using the new key values. Be sure! Once an access key is deleted, it cannot be recovered.
  7. For the original key, click Delete.

The new key is now in use and the original key is now inactive and cannot be used again.

↑ Back to top

Next Below are the products available on the AGCOD API

Last updated: Oct 14, 2021