How to rotate your app's LWA client secret

Your Login With Amazon (LWA) credentials (client secret) is like a password. Regularly rotating the LWA client secret that your app uses to authenticate is a security best practice. During rotation, only the client secret will change. The client identifier won’t change. Thus, this guide uses the term LWA client secret instead of LWA credentials.

There are two options to rotate your app’s LWA client secret:

Using Application Management API
Using Solution Provider Portal (SPP)

Application Management API

You can programmatically rotate your client secret using the Application Management API. For more information about how to use this API, see What is Application Management API? For API specifications, see Application Management API reference.

SPP

You can rotate the client secret in SPP by following these steps:

You'll notice a banner that says Action Required: Rotate LWA Credentials. This means rotate your LWA client secret.

The link to Learn More directs you to Amazon Selling Partner API page. The page also describes the process and includes a video for rotating the client secret. Only refer to this link if the steps describe here aren't sufficient.

From the LWA credentials column, select View.

The warning symbol, next to the View link, indicates that your app’s client secret rotation is getting closer to the next rotation date.

Select Rotate secret to generate a new LWA client secret for your app. The credential for client identifier won’t change. Only the client secret will change.

📘

Selecting the information symbol on the left side of the Rotate secret button displays a link, Learn more about LWA credentials rotation. Only refer to this link if the steps describe here aren't sufficient.

A warning message displays.

Read the warning message before proceeding. You’ll lose your current LWA client secret once you proceed. Write down this client secret for your future reference.

Select Rotate secret to proceed.

The new client secret displays. For future reference, copy your new LWA client secret and your next rotation deadline to a text file.

Select Done.

After you generate a new client secret, update your client secret for any apps that call the Amazon Business APIs. Your old client secret expires after seven days.

📘

Repeat steps 2 to 5 for each app that shows an expiration alert.

Error handling

{  
    "errors": [  
        {  
            "code": "Unauthorized",  
            "message": "Access to requested resource is denied.",  
            "details": "The LWA secret token you provided has expired."  
        }  
    ]  
}

This error occurs if you forgot to rotate your credentials in time. All API calls are blocked. Do these steps to resolve the issue:

Sign in to SPP.
Navigate to the SPP page that lists all your app.
From the LWA credentials column, select View.
Select Rotate secret to generate a new LWA client secret for your app.
Use the credentials displayed in Client secret.

If the issue persists, please contact abapi-integrations@amazon.com.

{  
 "error_description": "Client authentication failed",  
 "error": "invalid_client"  
}

This error occurs if you continue to use your old client secret seven days after generating a new one. Your app won’t have a valid access token to perform an API call. Do these steps to resolve the issue:

Sign in to SPP.
Navigate to the SPP page that lists all your app.
From the LWA credentials column, select View.
Select Rotate secret to generate a new LWA client secret for your app.
Use the credentials displayed in Client secret.

Frequently asked questions

Why do I need to rotate the LWA client secret on Amazon Business API app?
Your app’s LWA client secret is like a password. Even if you’re very careful with your access credentials, you may find yourself in a situation where your credentials have been exposed or compromised. Regular and timely rotation of LWA client secret helps secure your apps by limiting the lifespan of the credentials.

📘

Rotating client secret doesn’t impact end users. End users don’t need to re-authorize apps.

How often do I need to rotate the LWA client secret?
You must rotate your LWA client secret every 180 days. You have an option to rotate it more frequently if required by your company’s data security standards and practices.

Do I need to rotate the LWA client secret for each of my apps?
Yes. You’ll need to rotate your LWA client secret for each of your apps. For easy tracking, we recommend that you rotate your LWA client secret for all your apps at the same time.

Will I get notification if the LWA client secret is about to expire?
Yes. We’ll send you an email 30 days before the expiration of your LWA client secret. We’ll send reminders as you get closer to the expiration date. You’ll get the reminders through the primary email address associated with your developer account.

Can I cancel my old LWA client secret before the seven-day period?
If you need to cancel your old LWA client secret before the seven-day period or if the client secret has been compromised, please contact abapi-integrations@amazon.com.

How do I know if the client secret is rotated?
Once the client secret is rotated, you’ll notice a new expiration date on LWA credentials screen.

The expiration date is 180 days from the date you rotated your client secret.

Sample: You rotated your client secret on 2023-07-19T18:26:05.420Z. Your next rotation date is on 2024-01-15T18:26:05.420Z.

Is there an automated way to rotate and get the new client secret?
We don’t have an automated way to rotate the LWA client secret.

With client secret rotation, does this mean end users will have to re-authorize their apps every 180 days?
No. There’s no need to get new authorization from your customers. The existing refresh token will continue to work.