Authorization Header

All calls to Prime APIs will require 3P client to sign the request.

This section details the signing process. Clients create the AWS SIGv4 signature and passes it along with the request to Prime APIs which will be used for Authentication purposes. This signature is used by all AWS services (ex: DynamoDB).

Please do note that only Prime APIs follow AWS SIGv4 based authentication process and not LWA APIs which you may already be using. Authentication done by LWA APIs are specified in the LWA public documentation.

For valid signature generation, clients should follow these guidelines:

1) Create AWS Identity for generating Signature

Clients should use AWS IAM Role to make a call to Prime APIs. Prime APIs are hosted on AWS API Gateway. The calling AWS identity should have the permission to invoke the AWS API Gateway. This is enabled by granting right policy to the AWS identity.

We list below the mechanism for AWS IAM role:

• Follow the instructions listed here to create IAM role - https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create.html
• In the above link, make these changes at the relevant steps:
  • Select programmatic access.
  • Select “Attach existing policy”. Search for policy ‘AmazonAPIGatewayInvokeFullAccess’. Attach the policy.
  • Create the role.

2) Signature Generation Process

Clients can follow one of the following two options for generating the signature:

1. Creating signature using AWS Library [Recommended]:

   • AWS provides an SDK which takes care of generating the signature. As a client, you only need to pass in the required fields.
   • For Java language, please refer to the following SDK documentation. For other languages, you will find relevant links in the AWS documentation - https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/auth/AWS4Signer.html.
   • When using the SDK, you only need to set few required parameters. Most of the parameters are self explanatory apart from the below mentioned parameters:
     1. Set region name (method: setRegionName): Refer Appendix A to select the Prime region. The right Prime region to be used will depend on the customer country. For example, for US, it is ‘us-east-1’. For IN, it is ‘eu-west-1’.
     2. Set service name (method: setServiceName): For calling Prime APIs, please set it as “execute-api”.

2. Creating signature manually:

   • In case the AWS library is not available in the programming language used by you, you can then choose to manually generate the signature following the below mentioned steps.
   • Read the specifications present in this link here - https://docs.aws.amazon.com/general/latest/gr/sigv4_signing.html
   • The above link provides general documentation. A client would need to override some values for talking to Prime APIs. The parameters that needs to be overriden are mentioned below:
     1. Include host name in the signature calculation. The host name is the domain name of Prime. Please pick the domain name that is relevant for the Customer country.
     2. If you are using HTTP/2.0 protocol to make the request, then please contact Prime team. Additional header needs to be passed in that case.
     3. Value of Credential parameter in the signature:
        • Structure of the parameter is as follows: {accessKeyID}/{Date}/{region}/{serviceName}/aws4_request
        • accessKeyID = access key ID of your root AWS account or IAM role.
        • Date = YYYYMMDD format. It should match the value set in x-amzn-Date header.
        • region = Refer Appendix A to select the Prime region. Prime region to invoke will be based on the Customer country.
        • serviceName = execute-api

Sample signature for Prime APIs would look like this:

"Authorization: AWS4-HMAC-SHA256 Credential=<AWS account/ IAM role access key
id>/20210504/us-east-1/execute-api/aws4_request,SignedHeaders=x-amz-marketplace;
x-amz- request-id;host;x-amz-date,
Signature=9160882a20351d49ae497e7a37367c6165c62ec5060f7361050f43ec064410bc"

Below is the code snippet for AWS signature generation that can be used as a reference:

const aws4 = require('aws4');
import {v4 as uuidv4} from 'uuid';
const accessKeyId = "";
const secretAccessKey = "";
const sessionToken = ""
const lwaAccessToken = "";
const body = {
    benefitsStatus: 'Active',
    clientCustomerId: `clientCustomerIdValue`,
    linkChannel: 'Online'
}

// This function is responsible for returning the header required to call the Benefit Discovery API.
function awsSignature4HeaderForBenefitDiscoveryAPI() {
    const signer = aws4.sign({
        host: 'prime-apis.amazon.com',
        service: 'execute-api',
        region: 'us-east-1',
        path: `/v1/customer/benefits/BENEFIT_ID?customerIdentifierType=LWAAccessToken&customerIdentifier=${lwaAccessToken}`,
        headers: {
            'host': 'prime-apis.amazon.com',
            'x-amz-request-id': `${uuidv4()}`,
            'x-amz-marketplace': 'US'
        },
        method: 'GET'
    }, {
        accessKeyId: accessKeyId,
        secretAccessKey: secretAccessKey,
        sessionToken: sessionToken
    });
    return new Map(Object.entries(signer.headers));
}

// This function is responsible for returning the header required to call the Account Linking API.
function awsSignature4HeaderForAccountLinkingAPI() {
    const signer = aws4.sign({
        host: 'prime-apis.amazon.com',
        method: 'POST',
        service: 'execute-api',
        region: 'us-east-1',
        path: `/v1/customer/link-benefit/BENEFIT_ID? customerIdentifierType=LWAAccessToken&customerIdentifier=${lwaAccessToken}`,
        headers: {
            'host': 'prime-apis.amazon.com',
            'x-amz-request-id': `{uuidv4()}`,
            'x-amz-marketplace': 'US',
            'Content-Type': 'application/json'
        },
        body: JSON.stringify(body)
    }, {
        accessKeyId: accessKeyId,
        secretAccessKey: secretAccessKey,
        sessionToken: sessionToken
    });
    return new Map(Object.entries(signer.headers));
}

Appendix A - Prime API Regions

Please use the respective region based on the customer’s country where the deal construct between Amazon and Client is operational.

Region Name	Prime Domain Name	Countries	Region id to be used in Signature
North America Region	prime-apis.amazon.com	US, CA, MX	us-east-1
Europe Region	prime-apis.amazon.eu	UK, FR, IT, ES, IN, AE, SA, EG, NL, DE, TR	eu-west-1
Far East Region	prime-apis.amazon.jp	JP, SG, AU	us-west-2