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
- Implementing Signature Version 4
- Signed Request Example
- Troubleshooting your signature signing code
- Secure Data Transmission
- Handling Keys
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 |
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:
- Signing AWS Requests with Signature Version 4
- Example—A Simple GET Request with Parameters
- Troubleshooting AWS Signature Version 4 Errors
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"
}
}
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 toapplication/json
will succeed.
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.
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:
- In the Incentives API portal, click
API security credentials
. - Click
Create new access key
. - Update all your applications to use the new access key.
- Confirm that all requests to Incentives API operations are succeeding using the new key values.
- For the original key, click
Deactivate
. - 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.
- 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.
Next Below are the products available on the AGCOD API
- Digital Gift Cards
- Pin on Receipt for B&M Guide
- Activate Physical Cards
- Point of Sale Activation
- Login and Receive
- LoadAmazonBalance (Amazon Cash)
- Product Voucher Guide
Last updated: Oct 14, 2021