---
title: Key Upgrade API
url: amazon-pay-registration/keyupgradeapi.html
---

The Amazon Pay CV2 Key Upgrade API allows you to exchange Amazon Pay CV1 Credentials (***AWS Access Key Id*** and ***Secret Access Key***) against credentials required for Amazon Pay CV2 APIs programmatically.
Using the AWS AccessKey Id and a signature calculated with the Secret Access Key, call the GetPublicKeyId action to generate a Public Key Id that will be used to make API calls to the CV2 API.  

**How to use the publicKeyId :** 
The Public Key ID you receive will be set in the **authorization** header of each CV2 API call.
Here is an example of a request using the public key Id:

```
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
```
* TOC
{:toc}

## Generating Private and Public key pair

In order to generate the key pair required for the key upgrade, see the [Manually Generating Key Pairs](https://developer.amazon.com/docs/amazon-pay-api-v2/manually-generating-key-pairs.html#generating-key-pair) guide.

## Request

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

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

**Path:** `/live/v2/publicKeyId`

### Request query parameters 

|Parameter	|Description	|Valid values	|
|---	|---	|---	|
|Action (required) Type:String	|The action to be performed	|GetPublicKeyId	|
|---	|---	|---	|
|AWSAccessKeyId (required) Type:String	|The MWS**AccessKeyId** that you received when you registered for Amazon MWS.	|	|
|MerchantId (required) Type:String	|Your Amazon Pay merchant ID	|	|
|PublicKey (required) Type:String	|The public key from your self-generated private/public key pair	|Your public key string (the text value of the **public.pem** file generated in the steps above)	|
|SignatureVersion (required) Type:String	|Which signature version is being used. This is Amazon MWS-specific information that tells Amazon MWS the algorithm you used to form the string that is the basis of the signature.	|2	|
|SignatureMethod (required) Type:String	|The HMAC hash algorithm you are using to calculate your signature. Both HmacSHA256 and HmacSHA1 are supported hash algorithms, but Amazon recommends using HmacSHA256.	|HmacSHA256	|
|Signature (required) Type:String	|For steps to calculate the signature using the ***Secret Access Key***, see [How to calculate the signature](https://developer.amazon.com/de/docs/amazon-pay-registration/getpublickeyid.html).	|	|
|Timestamp (required) Type:DateTime	|The current time	|The current date and time or the expiration date and time for the request in [ISO 8601 date time format](http://docs.developer.amazonservices.com/en_US/dev_guide/DG_ISO8601.html).	|

See additional description of parameters [Required request parameters](https://docs.developer.amazonservices.com/en_US/dev_guide/DG_RequiredRequestParameters.html)

Watch our Amazon Pay University video on [Locating your MWS Keys](https://www.youtube.com/watch?v=oHp4Hv5_MBA)

### Successful response headers

|Header	|Description	|
|---	|---	|
|Content-Type	|text/json	|
|---	|---	|

### Successful response elements

|Parameter	|Description	|
|---	|---	|
|publicKeyID Type:String	|Public Key ID that will be used to make future CV2 API calls	|
|---	|---	|
|publicKeyIDName Type:String	|Public Key ID Name that will be used to make future CV2 API calls	|

## Sample requests and responses

**Request message example**

* **Note :** In the actual Query request, there are no spaces or newline characters. The request is a continuous line of text. The version below is formatted for human readability.

```
Accept: application/json  
Content-type: application/json
GET https://pay-api.amazon.com/live/v2/publicKeyId?
MerchantId=AKI12345
&AWSAccessKeyId=AKIAIOSFODNN7EXAMPLE 
&Action=GetPublicKeyId
&SignatureMethod=HmacSHA256 
&SignatureVersion=2 
&Timestamp=2022-07-28T15%3A19%3A30
&PublicKey=SamplePublicKey
&Signature=<signature_calculated_with_secret_key>
```

See [here](https://developer.amazon.com/docs/amazon-pay-registration/getpublickeyid.html) for detailed information on how to generate the value for the request parameter *Signature*.

**Example response** 

```
HTTP/1.1 201 Created
Server: Server
Date: Thu, 01 Dec 2022 03:04:33 GMT
Content-Type: application/json
Content-Length: 105
Connection: keep-alive
x-amz-rid: H43Z5RG0QPKP6NPHTEST
X-Amz-Pay-Request-Id: 06bf7dc2-b364-4c08-b5ca-4761ba526bd0
Vary: Content-Type,Accept-Encoding,User-Agent
Strict-Transport-Security: max-age=47474747; includeSubDomains; preload

{"publicKeyId":"AFZO6SDUYY5P6LEAZRJ2TEST","publicKeyIdName":"TEST345_KRX_dv9zPjzYvNHJANrEsSmiVEc"} 
```

**Error response message example**

```
HTTP/1.1 400 Bad Request
Server: Server
Date: Wed, 30 Nov 2022 22:38:07 GMT
Content-Type: application/json
Content-Length: 132
Connection: keep-alive
x-amz-rid: 954JA5DWNKDS2WJENNBS
X-Amz-Pay-Request-Id: f897b885-bda1-472c-b9f4-b0d079ef6056
Vary: Content-Type,Accept-Encoding,User-Agent
Strict-Transport-Security: max-age=47474747; includeSubDomains; preload

{"reasonCode":"InvalidRequest","message":"The query string parameters [AWSAccessKeyId] are required and are missing in the request"}
```

### Error response elements

|Parameter	|Description	|Type	|
|---	|---	|---	|
|Code	|Machine readable error code	|String	|
|---	|---	|---	|
|Message	|Human-readable error description	|String	|

### Error response message examples

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

|Status	|Error code	|
|---	|---	|
|400 BAD_REQUEST	|InvalidParameterValue	|
|---	|---	|
|400 BAD_REQUEST	|InvalidRequest	|
|401 UNAUTHORIZED	|InvalidRequestSignature	|
|403 FORBIDDEN	|AccessDenied	|
|500 INTERNAL_SERVER_ERROR	|InternalServerError	|
|503 SERVICE_UNAVAILABLE	|ServiceUnavailable	|

Generic errors can be found [here](https://developer.amazon.com/de/docs/amazon-pay-api-v2/error-handling.html).
* * *