DEV Community

operix
operix

Posted on

Rotating a Shopify app secret: generate, revoke, pull, deploy, and why the obvious order doesn't work

Shopify Dev Dashboard and CLI, measured on 2026-09-16, 2026-09-30 and 2026-10-22 on our own apps, hosted on Railway. No secret value appears in this post, and the point of most of it is to keep it that way in yours too.

We've rotated client secrets three times this autumn. Twice because we leaked one ourselves, once because our hosting provider had an incident and told everyone to. The order you'd guess, make the new secret, deploy it, retire the old one, doesn't work with the Shopify CLI.

How we leaked our own secret, twice

On 2026-09-16, while reading the app's Credentials page, a browser-automation step dumped the value of every input and textarea on the page. That page holds the client secret as the plain value of an input. The secret went into a log file, and from there the only honest move was to rotate. On 2026-09-30 we did the same thing on the settings page of a newer app, Upload Box.

The rule since then: on any page that shows credentials, screenshots and clicks only, never a script that reads the DOM. When a value is needed, the CLI writes it to a file and a shell variable carries it from there; nothing passes through a screen or a clipboard.

Why "generate, deploy, revoke" doesn't work

Dev Dashboard → your app → Settings → Credentials → Rotate → Generate new secret. You now have Old and New side by side, and the dialog says: Webhooks won't use the new secret until you revoke the old one.

The part the dialog doesn't say: shopify app env pull keeps returning the old secret until you revoke. So there's no CLI path to fetch the new value, put it on the server, and only then revoke. The order becomes:

  1. Rotate → Generate new secret.
  2. Revoke the old one. The confirmation says "ending in XXXX"; we check those four characters against the tail of the value currently in .env before clicking.
  3. SHOPIFY_FLAG_ENV_FILE=/tmp/secret.env shopify app env pull. The --env-file flag got swallowed by node in our setup, so we pass it as an environment variable.
  4. Put it on the host from the file, via shell expansion, never by typing: railway variables --set "SHOPIFY_API_SECRET=$(sed -n 's/^SHOPIFY_API_SECRET=//p' /tmp/secret.env)". On Railway a variable change redeploys on its own.
  5. Update the local .env the same way and delete the scratch file.

Between steps 2 and 4 there are a few minutes where Shopify signs webhooks with the new secret and your server verifies with the old one. Shopify retries failed deliveries for 48 hours, so nothing is lost, provided your deploy actually goes out that day. More on that below. The steps now live in a script that pulls through the scratch file, refuses to continue if the pulled value equals what the host already holds (meaning the revoke hasn't happened), and prints variable names only.

Proving it with three signatures

A green deploy isn't proof. We check the swap with a side-effect-free webhook, customers/data_request, on a made-up payload, signed three ways:

Key used to sign Expected
random garbage 401
the old secret 401
the new secret 200

The first row shows the verifier isn't a no-op, the second that the old secret is dead on your side, the third that the new one is live, and only all three together show the rotation happened. The signing script reads the key from a file so it never lands in argv, shell history or ps:

# sign.py <key-file> <body-file>  -> prints the X-Shopify-Hmac-Sha256 value
import base64, hashlib, hmac, sys
key = open(sys.argv[1], "rb").read().strip()
body = open(sys.argv[2], "rb").read()
print(base64.b64encode(hmac.new(key, body, hashlib.sha256).digest()).decode())
Enter fullscreen mode Exit fullscreen mode

The 502 that followed, and whose fault it was

On 2026-09-30, minutes after rotating Upload Box, the first storefront upload failed with a 502 and the server log said "Missing access token". Opening the app in the admin once fixed it.

The chain, from the logs the same evening: revoking the old secret invalidated the offline access token that had been issued under it. The next Admin API call got a 401. The Shopify library did the right thing: it cleared the stored token and threw a Response meant to send App Bridge through a token exchange. Our loader had try { admin.graphql(...) } catch {} around that call, which swallowed the Response. The session stayed tokenless, and the App Proxy route, which has no exchange path of its own, had nothing to use.

The fix is one line at the top of each such catch, if (e instanceof Response) throw e;, plus a test that fails if someone removes it. Three sibling apps had the same pattern; one was fixed within a week, the other two on 20 October.

Shopify's docs say tokens are bound to the secret that issued them and die with it. The revoke dialog had warned about exactly this and we clicked through it; we only read the docs properly three weeks later.

Doing it without a gap when real stores are installed

On 2026-10-21 Railway disclosed a security incident around stored environment variables and recommended rotating them. The next day we set out to rotate the secrets of all eight apps. Five had no external stores, so the order above was fine and they were done that day. Three did (five, two and two stores), and for those a few minutes of broken webhooks plus every store's offline token dying at revoke wasn't acceptable.

Our library, @shopify/shopify-api 15, takes exactly one secret. With a zero-store app, on 2026-10-22 at 14:32, we checked what Shopify does during the overlap: webhooks, admin session tokens and App Proxy signatures all kept using the old secret while both existed. That gave us a four-step order (tested in parts, not yet run end to end):

  1. Rotate → Generate new secret, and leave the old one in place. Store the new value in a second variable, SHOPIFY_API_SECRET_NEW. The main SHOPIFY_API_SECRET stays old.
  2. Deploy. On boot, if _NEW is set, a one-time script walks every stored offline session that has a refresh token, refreshes it through a second library instance built with the new secret, and saves the result under the same session id. Online sessions and sessions without a refresh token are skipped, and a response for a different shop or an empty token isn't saved. The log line is counts only, for example [repin] {"total":7,"ok":5,"failed":0,"skipped":2,"expired":0}.
  3. Revoke the old secret.
  4. Deploy again with SHOPIFY_API_SECRET set to the new value and _NEW removed.

Steps 2 to 4 have to happen within about ten minutes. The tokens refreshed in step 2 live on a server that's still configured with the old secret. Roughly an hour later that server would refresh them again under the old secret, and a merchant opening the app in between triggers a token exchange under the old secret, which invalidates the other refresh token for that shop. Either one quietly undoes step 2. After step 4 we call the Admin API once per offline session and count 401s; zero is the target, and a non-zero shop recovers the next time its merchant opens the app.

A crash in the middle of step 2 is safe, since Shopify keeps the old refresh token valid until the new one is actually used; a failed save leaves a working row behind.

Don't revoke on a day you can't deploy

The same 10-22, Railway had paused builds. For the five apps we revoked anyway, reasoning that with no external stores nobody was affected. One of them had picked up an external store by then, and its order webhooks sat at 401 overnight until the redeploy went through on 2026-10-23 at 06:54; Shopify retried and they arrived. So a real store was affected, just not visibly; with more stores it would've been a day of dead webhooks. The revoke now waits until we've seen a deploy succeed that day.

Open questions after three rotations

We don't know whether a refresh token issued under the old secret can still be refreshed after the revoke; the repin step makes it irrelevant for us. We haven't timed how long a revoke takes to reach webhook signing either. The docs say up to about an hour; we've never measured it, since the 401s were already in the logs by the time we looked. And the four-step order has been exercised piece by piece, not yet on an app with stores installed.

We'll be doing this again, probably after the next careless log line. Of everything above, we'd keep the three signatures if we had to drop the rest; that check alone shows the rotation happened rather than that the buttons were clicked.


Written by a backend engineer with ten years of experience, building small Wix and Shopify apps as operix.

Upload Box, the app behind the 502 above, is on the Shopify App Store: https://apps.shopify.com/upload-box?utm_source=blog&utm_medium=article&utm_campaign=shopify-app-secret-rotation-order

More from the same notebook: Your Wix widget loads from whichever deployment rendered the page, and that render can be cached for 35 hours · npx wix release does not build

Top comments (1)

Collapse
 
danorie profile image
MinSoo Kim •

About the 48-hour retry window. When my uninstall handler returned 500 on a review store, app/uninstalled and shop/redact were each delivered nine times with exponential backoff, and the last attempt in my logs came about four hours after the first. Then nothing.

Your order webhooks sat at 401 overnight and still arrived. So order topics may be on a longer schedule than those two. Did they land on the first retry after your redeploy, or later?