Application Management API v2023-11-30 Use Case Guide

API Version: 2023-11-30

What is the Application Management API?

The Selling Partner API for Application Management lets you programmatically rotate the client secret on registered applications.

You must register an Amazon Simple Queue Service (Amazon SQS) queue for receiving credentials before you call the rotateApplicationClientSecret API operation. When you make the API call, a new client secret is created for the application that you're calling. The new credential is sent to your preregistered SQS queue along with the expiry time for the old credentials. You must update your application to use the new credential before the old credential expires.

🚧

Give Amazon permission to write to your SQS queue

Be sure to follow the steps in Grant Selling Partner API permission to write to your SQS queue so Amazon can send notifications to your SQS queue.

Terminology

• Client ID: Part of your Login with Amazon (LWA) credentials. To get this value, refer to Viewing your application information and credentials.
• Client Secret: Part of your LWA credentials. To get this value, refer to Viewing your application information and credentials.
• Credential Rotation: The process of creating a new client secret and invalidating the old client secret.

Tutorial: Credential rotation notification

Learn how to set up a notification that alerts you when your credentials need to be rotated.

Prerequisites:

To successfully complete this tutorial, you must have access to:

• The Developer Console
• Amazon SQS
• An SQS queue

Step 1. Grant Selling Partner API permission to write to your SQS queue

To receive notifications, you must grant Selling Partner API permission to write to your SQS queue.

1. Open the AWS Management Console and sign in with your AWS credentials.
2. From the console, open Amazon Simple Queue Service.
3. Select the Standard queue where you want to receive notifications.
4. Choose the Access Policy tab.
5. From the Access policy (Permissions) section, select Edit. The Edit Test Queue page opens.
6. Scroll down to Access policy, then select the Policy generator link. The AWS Policy Generator opens in a new tab.
7. In Step 1 of the policy generator, select SQS Queue Policy.
8. In Step 2 of the policy generator:
   a. Set Effect to Allow.
   b. Set Principal to 437568002678.
   c. Set Actions to SendMessage and GetQueueAttributes.
   d. Enter the SQS ARN value in Amazon Resource Name (ARN).
   e. Choose Add Statement and verify the details.
9. In Step 3 of the policy generator, select Generate Policy. A dialog box with the new policy opens.
10. Copy the policy.
11. Navigate back to the Amazon SQS queue, open the Access policy tab, then paste the policy into the Access Policy (Permissions) section.
12. Save the changes.
13. Reference the queue's Details section and note the ARN for this queue, as you need it to register your queue in the next step.

Step 2. Register your SQS queue to receive expiring credential notifications

1. Sign in to your developer account on Seller Central, Vendor Central, or Developer Central. Navigate to the Developer Console page that lists all your applications.
2. Select Notification Preferences.
3. On the Subscription page, find the application for which you want to receive expiring credential notifications.
4. In the Application Client Secret Expiry row, select the SQS ARN where you want to receive the expiring credential notification.

Step 3. Listen for expiring credentials

Amazon sends a notification to the registered queue when the application is approaching LWA credential expiration. You can listen to your SQS queue and rotate your credentials when you receive the notification.

Use an Amazon SQS client to receive the message from your pre-registered queue. Follow the ReceiveMessage documentation.

Notification example

{
  "notificationVersion":"1.0",
  "notificationType":"APPLICATION_OAUTH_CLIENT_SECRET_EXPIRY",
  "payloadVersion":"2023-11-30",
  "eventTime":"2024-01-10T02:15:10.045Z",
  "payload":{
    "applicationOAuthClientSecretExpiry":{
      "clientId":"amzn1.application-oa2-client.xxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      "clientSecretExpiryTime":"2024-03-03T22:06:39.224Z",
      "clientSecretExpiryReason":"PERIODIC_ROTATION"
    }
  },
  "notificationMetadata":{
    "applicationId":"amzn1.sp.solution.xxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "subscriptionId":"a275c00d-260c-4xxxxxxxxxxxf25",
    "publishTime":"2024-01-10T02:15:14.269Z",
    "notificationId":"e7e27216-4970-477a-882c-e4xxxxxxxxxxxxxdc"
  }
}

Tutorial: Rotate your application's client secret

Learn how to rotate your client secrets using the rotateApplicationClientSecret operation.

Prerequisites:

To successfully complete this tutorial, you must have:

• Access to the Developer Console
• Access to Amazon SQS (and a new SQS queue)
• The application's current client credentials

Step 1. Register your SQS queue to receive new credentials

1. Sign in to your developer account on Seller Central, Vendor Central, or Developer Central. Navigate to the Developer Console page that lists all your applications.
2. Select Notification Preferences.
3. On the Subscription page, find the application for which you want to receive the expiring credential notification.
4. In the Application Client New Secret row, enter the SQS queue where you want to receive the new credential.

Step 2. Call the rotateApplicationClientSecret operation

Call the rotateApplicationClientSecret operation with the application credential that you want to rotate. The following steps show the workflow, with screenshots from the Postman tool.

1. Generate an LWA Access Token by calling the token's API endpoint (https://api.amazon.com/auth/O2/token) using client_id, client_sceret, grant_type, and scope in the POST call body as x-www-form-urlencoded parameters.

   

2. Use the LWA Access Token from Step 1 in the x-amz-access-token header of the rotateApplicationClientSecret with the endpoint URL https://sellingpartnerapi-na.amazon.com/applications/2023-11-30/clientSecret.

   

Response

This operation doesn't return a response. If the credential is successfully rotated, you receive a 204 response and the new credential is sent as a notification to the registered SQS queue.

❗️

Rotate your credential after calling

The credential you use to call rotateApplicationClientSecret expires after seven days. If you don't update your credential before it expires, your application will stop working.

Request example

POST https://sellingpartnerapi-na.amazon.com/applications/2023-11-30/clientSecret

Response

This operation doesn't return a response. If the credential is successfully rotated, you receive a 204 response and the new credential is sent as a notification to the registered SQS queue.

Step 3. Get the latest client secret from your SQS queue

Use an Amazon SQS client to receive the message from your pre-registered queue. Follow the ReceiveMessage documentation for receiving messages in your SQS queue.

Response

Response example

{
  "notificationVersion": "1.0",
  "notificationType": "APPLICATION_OAUTH_CLIENT_NEW_SECRET",
  "payloadVersion": "2023-11-30",
  "eventTime": "2024-01-10T22:09:17.456Z",
  "payload": {
    "applicationOAuthClientNewSecret": {
      "clientId": "amzn1.application-oa2-client.6XXXXXXXXXXXXXXXXXXXXXXXXX",
      "newClientSecret": "amzn1.oa2-cs.v1.8b6XXXXXXXXXXXXXXXXXXXXXXXXX",
      "newClientSecretExpiryTime": "2024-07-08T22:09:17.198Z",
      "oldClientSecretExpiryTime": "2024-01-17T22:09:17.180Z"
    }
  },
  "notificationMetadata": {
    "applicationId": "amzn1.sp.solution.6XXXXXXXXXXXXXXXXXXXXXXXXX",
    "subscriptionId": "8594dc0e-78dc-4b05-83a4-a6XXXXXXXXXXXXXX",
    "publishTime": "2024-01-10T22:09:18.706Z",
    "notificationId": "b0805eb9-78f7-49bb-ac0e-XXXXXXXXXXX"
  }
}

General recommendations

• Use the expiration notification: We recommended using the expiration notification to invoke a rotation. The expiry time that is in the expiry notification serves as an indicator of when you need to rotate credentials.

• Enable server-side encryption for SQS: For security, enable SQS server-side encryption and grant Amazon access to write to your SQS queue. For more information, refer to Grant Selling Partner API permission to write to your SQS queue.

• Store your credentials in your applicaton's credential vault: For security, make sure you don't pass the secret in an unencrypted format. We recommended storing credentials in a credential vault, such as KMS custom keys store.

• Testing Application Management API integration: Use the Application Management API on a draft application before using it on a production application. You can then test your infrastructure for loading the secret from your SQS queue to your application secret vault independently of your production application. After you receive the new secret for the draft application, use it to make sure it works.