Application Management API v2023-11-30 Use Case Guide
How to use the Application Management API.
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.
- Open the AWS Management Console and sign in with your AWS credentials.
- From the console, open Amazon Simple Queue Service.
- Select the Standard queue where you want to receive notifications.
- Choose the Access Policy tab.
- From the Access policy (Permissions) section, select Edit. The Edit Test Queue page opens.
- Scroll down to Access policy, then select the Policy generator link. The AWS Policy Generator opens in a new tab.
- In Step 1 of the policy generator, select SQS Queue Policy.
- In Step 2 of the policy generator:
a. Set Effect to Allow.
b. Set Principal to 437568002678.
c. Set Actions toSendMessage
andGetQueueAttributes
.
d. Enter the SQS ARN value in Amazon Resource Name (ARN).
e. Choose Add Statement and verify the details. - In Step 3 of the policy generator, select Generate Policy. A dialog box with the new policy opens.
- Copy the policy.
- Navigate back to the Amazon SQS queue, open the Access policy tab, then paste the policy into the Access Policy (Permissions) section.
- Save the changes.
- 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
- 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.
- Select Notification Preferences.
- On the Subscription page, find the application for which you want to receive expiring credential notifications.
- 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"
}
}
Name | Description |
---|---|
clientId | Part of your LWA credentials. Type: string |
clientSecretExpiryTime | The date the clientId credential expires (in ISO 8601 format). Type: DateTime |
clientSecretExpiryReason | The reason for the expiration. Type: string |
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
- 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.
- Select Notification Preferences.
- On the Subscription page, find the application for which you want to receive the expiring credential notification.
- 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
rotateApplicationClientSecret
operationCall the rotateApplicationClientSecret
operation with the application credential that you want to rotate. The following steps show the workflow, with screenshots from the Postman tool.
-
Generate an LWA Access Token by calling the token's API endpoint (
https://api.amazon.com/auth/O2/token
) usingclient_id
,client_sceret
,grant_type
, andscope
in thePOST
call body asx-www-form-urlencoded
parameters. -
Use the LWA Access Token from Step 1 in the
x-amz-access-token
header of therotateApplicationClientSecret
with the endpoint URLhttps://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
Name | Description |
---|---|
clientId | Part of your LWA credentials. Type: string |
newClientSecret | The newly generated client secret. Type: string |
newClientSecretExpiryTime | The date the newly generated secret expires (in ISO 8601 format). Type: DateTime |
oldClientSecretExpiryTime | The date when the old credential expires (in ISO 8601 format). Ensure your application uses the new secret when requesting access tokens before this date. Type: DateTime |
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.
Updated 2 months ago