Rotating Your Shared Secret
Rotating your shared secret means replacing it with a new one. Doing so protects your app and your Etsy account in a few situations:
- If your secret may have been exposed. If it was leaked, shared by mistake, or committed to code, replacing it makes the old one useless to anyone else.
- When someone with access leaves. A former teammate or contractor can no longer use a secret that no longer works.
- As routine good security practice. Replacing secrets from time to time limits how long any one copy, such as one in an old backup or log, can be misused.
You don't have to rotate on a schedule, but you should rotate right away if you suspect your secret has been exposed. The Developer Portal lets you do this yourself, without downtime and without contacting Etsy.
Your app's API credentials consist of two parts: a keystring, which identifies your app, and a shared secret, which proves the request comes from you. The keystring is permanent and can't be changed. The shared secret is the part you can rotate.
Before you start#
Your existing secret stays valid until you choose to rotate it. Nothing changes for your app unless you start a rotation. You do not need to take any action for your app to keep working.
How rotation works: Primary and Secondary secrets#
Each app has a Primary secret. This is the secret you have today, shown in the Developer Portal as "Shared Secret."
When you start a rotation, Etsy generates a Secondary secret, shown as "Your new secret." While both exist, both are accepted at the same time.
| Label | What it is | When it exists |
|---|---|---|
| Primary | Your current, original secret. | Always. Every app must have one. |
| Secondary | A new secret generated for the rotation. | Only during a rotation window. |
Why both secrets are accepted at once#
Most apps run in more than one place: multiple servers, background jobs, staging environments, secrets managers, shared integrations. You can't update all of them at the same instant. If Etsy only accepted the new secret, any system you hadn't updated yet would start failing the moment you generated it.
Accepting both secrets during the rotation window lets you move each system to the new secret at your own pace, with no downtime. Systems still using the old secret keep working, and systems you've already updated work too.
The window is not meant to stay open indefinitely. Two valid secrets are less secure than one, so finish the rotation as soon as you reasonably can. A rotation that is never completed or canceled is eventually completed for you automatically: your original secret is deleted and your new secret is promoted (see Automatic completion of unfinished rotations).
The rotation flow#
Step 1: Generate a new secret#
- Open your app in the Developer Portal
- Choose the Rotate shared secret option
- Select Generate a new secret.
- Copy the new secret and store it somewhere safe, such as your secrets manager.
Your new secret now appears as the Secondary secret. Your original secret is still the Primary secret and continues to work.
You can have only one Secondary secret at a time. If a rotation is already in progress, finish it or cancel it before starting another.
Step 2: Deploy the new secret to your clients#
Update every place your original secret is used, for example:
- Production servers
- Background jobs and scheduled tasks
- Staging and development environments
- Secrets managers and CI/CD variables
- Shared or third-party integrations that call Etsy on your behalf
Because both secrets are accepted, you can roll this out gradually.
Step 3: Test#
Before moving on, confirm that requests from every updated system succeed using the new secret. Check each environment, not only one.
Step 4: Complete the rotation (delete the original secret)#
When everything is using the new secret, select I've completed the rotation and confirm.
This permanently deletes your original (Primary) secret. At that point:
- Your new secret is automatically promoted to Primary.
- A secondary secret no longer exists, and the rotation is complete.
- Any system still using the original secret will immediately start failing.
- This can't be undone.
If you aren't sure every system has been updated, don't complete the rotation yet. Both secrets keep working until you do.
Cancelling the Rotation#
If something goes wrong during the rotation, you can cancel it at any point before completing it.
Select Cancel, keep original secret. This deletes the Secondary secret only.
- Your original (Primary) secret is untouched and keeps working.
- The new secret stops working, so revert any system you already updated to the original secret.
- You can start a new rotation later and receive a freshly generated secret.
Automatic completion of unfinished rotations#
A rotation is not meant to stay open indefinitely. If you generate a new (Secondary) secret but never complete or cancel the rotation, Etsy completes it for you after a grace period, counted from the moment you generated the new secret. We do this for security: a rotation that was started and never canceled is treated as a sign that your original secret may be compromised, so it is removed rather than kept.
The length of the grace period can change, so it isn't listed here. Check the Developer Portal for the current value: while a rotation is in progress, the rotation panel shows how long both secrets will keep working before the original is automatically deleted.
When this happens:
- Your original (Primary) secret is permanently deleted and stops working. Any system still using it will start failing.
- Your new (Secondary) secret is automatically promoted to Primary and keeps working.
- There is no Secondary secret anymore, and the rotation is complete. This can't be undone.
- You can start a new rotation at any time.
If you have already deployed the new secret everywhere, nothing changes for your app, even if you forgot to select I've completed the rotation. If some systems still use the original secret, update them before the grace period ends, or cancel the rotation to keep your original secret.
Rotations that are completed or canceled before the grace period ends are never affected.
Expiration reminder#
Etsy sends a reminder to the developer 2 days before an unfinished rotation is due to be completed automatically. The reminder is sent at most once per rotation and includes:
- Which app the secret belongs to
- When the original secret will be deleted and the new secret promoted
- A link to the Developer Portal so you can complete or cancel the rotation
No reminder is sent if you have already completed or canceled the rotation.
Summary#
| Action | What happens to the Primary secret | What happens to the Secondary secret |
|---|---|---|
| Generate a new secret | Unchanged, still valid | Created, valid |
| Complete the rotation (delete Primary) | Deleted | Promoted to Primary |
| Cancel the rotation (delete Secondary) | Unchanged, still valid | Deleted |
| Grace period ends with no action | Automatically deleted | Automatically promoted to Primary |
Frequently asked questions#
Do I have to rotate my secret? No. Your existing secret remains valid until you choose to rotate it.
Will my app go down while I rotate? Not if you follow the steps above. Both secrets are accepted until you complete the rotation, so you can update your systems one at a time.
Can I have more than one new secret at once? No. An app can have one Primary and at most one Secondary secret at a time.
Can I delete my original secret without generating a new one? No. An app must always have a Primary secret, so the original can only be deleted as part of completing a rotation, which promotes the new secret.
What happens if I generate a new secret and then forget to complete the rotation? After the grace period, your original secret is deleted automatically and your new secret is promoted to Primary. If you already deployed the new secret, your app keeps working. If you didn't, systems still using the original secret will start failing, so finish updating them or cancel the rotation before the grace period ends. The length of the grace period is shown in the Developer Portal. See Automatic completion of unfinished rotations.
What if I think my secret has been exposed? Start a rotation right away, deploy the new secret, and complete the rotation to invalidate the exposed secret.