V2 Authorization Tokens

Description

Call the AuthorizationTokens operation to retrieve a delegated authorization token used in order to make API calls on behalf of a merchant. This token is needed to make delegated calls in our new V2 version of the API.

How to use the v2 Authorization Token

You can add the V2 Authorization Token as a header in your API calls. The header key is: X-Amz-Pay-AuthToken
Here is an example of a request using the V2 Authorization Token:

X-Amz-Pay-AuthToken: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9....
X-Amz-Pay-Date: 20190305T024410Z
Content-type: application/json

POST https://pay-api.amazon.com/live/v1/deliveryTrackers       

{
    "merchantId": "12345"
}

Request

You can call the HTTP GET request with the endpoint, path, headers, and parameters specified below.

Region Endpoint
NA pay-api.amazon.com
EU pay-api.amazon.eu
JP pay-api.amazon.jp

Path: /live/v1/authorizationTokens/{mwsAuthToken}?merchantId={merchantId}

Request headers

Header Description Type
Authorization
(required)		 The signature algorithm, public key ID, signed headers, and the signature in the following format: Signature_Algorithm PublicKeyId=publicKeyId, SignedHeaders=SignedHeaders, Signature=signature String
X-Amz-Pay-Date
(required)		 The time at which the signature was generated. The signature, including timestamp, is generated in the payload. The date is in format YYYYMMDD’T’HHMMS’Z’ in ISO 8601 format. String

Request path parameters

Parameter Description Type
mwsAuthToken
(required)		 The MWS Auth Token that the solution provider currently uses to make V1 API calls on behalf of the merchant. String

Request query parameters

Parameter Description Type
merchantId
(required)		 The Amazon Pay merchant Id. String

Successful response elements

Parameter Description Type
authorizationToken HS256 encoded JWT Token that will be used to make V2 API calls on behalf of the merchant. String

Sample requests and responses

Request message example

Host: pay-api.amazon.com
Accept: application/json
Authorization: AMZN-PAY-RSASSA-PSS PublicKeyId=f4fc06fc-c5a7-11e7-abc4-cec278b6b50a, SignedHeaders=content-type;x-amz-pay-date, Signature=4164128ec5d1b9da1700167ab2ccda8125f472c8bb9de447cebf5d741ee317c8

X-Amz-Pay-Date: 20190305T024410Z
Content-type: application/json

GET https://pay-api.amazon.com/live/v1/authorizationTokens/amzn.mws.123456789?merchantId=aX123BFs343

Successful response message example

HTTP/1.1 200 OK 
Host: pay-api.amazon.com
Content-type: application/json
{
  "authorizationToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"
}

Error response message example

HTTP/1.1 400 Bad Request 
Content-Type: application/json; 
{ 
    "reasonCode": "InvalidParameterValue", 
    "message": "The merchantId that you submitted in this request is invalid.”
}

Error response elements

Parameter Description Type
reasonCode Machine readable error code String
message Human-readable error description String

Error response elements

Parameter Description Type
errorCode Machine readable error code String
errorMessage Human-readable error description String

Error response codes

If there is a problem fulfilling your request, you will receive an HTTP error response. The error codes for the AuthorizationTokens API request include:

Status Error code Description
400 InvalidHeaderValue You submitted an invalid value for at least one of the header parameters of your API call.

For details, check the message element in the API response.
400 InvalidParameterValue You submitted an invalid value for at least one of the parameters of your API call.

For details, check the message element in the API response.
400 InvalidRequestFormat You submitted a request in invalid JSON format. Please validate request body format.
401 UnauthorizedAccess The specified merchant account is not authorized to execute this request.
403 InvalidRequestSignature The signature in the Authorization header of your API call is invalid.

For details, check the message element in the API response.
403 InvalidAuthorizationToken The token and merchantId combination specified is invalid.
404 ResourceNotFound Couldn’t find requested resource.
405 RequestNotSupported HTTP method not supported.

For details, check the message element in the API response.
500 InternalServerError There was an unknown error in the service.
503 ServiceUnavailable The service is currently unable to handle the request, due to a temporary overloading or maintenance.