Authenticate a standalone or API-only app

Standalone and API-only apps run outside the Shopify admin, unlike embedded apps. A standalone app serves its own UI, and an API-only app has no UI and runs as a server-side integration. Because they can't use ID tokens, they authenticate using the OAuth authorization code grant flow: redirect the merchant to Shopify, get their approval, and exchange a code for an access token.

Info

If your app only acts on stores in your own Shopify organization, use the client credentials grant instead. It skips the merchant authorization flow. To learn how authentication works for other common approaches, see About app authentication.

Anchor to What you'll learnWhat you'll learn

In this tutorial, you'll learn how to do the following tasks:

Redirect a merchant to Shopify's authorization page
Validate the callback Shopify sends back to your app
Exchange the authorization code for an offline access token
Make authenticated GraphQL Admin API requests

Requirements

App credentials

You have your app's client ID and client secret from the Dev Dashboard.

Redirect URI

You've added your app's redirect URI to your app's settings in the Dev Dashboard, or to the [auth] section of your shopify.app.toml.

Access scopes

You know which access scopes your app requires.

Project

Language:

View on GitHub

Anchor to Redirect to Shopify's authorization pageRedirect to Shopify's authorization page

Send the merchant to Shopify to approve the access your app is asking for. Shopify presents a permissions prompt, and the merchant approves or denies it.

Anchor to Build the authorization URLBuild the authorization URL

Construct the authorization URL and redirect the merchant to it. Include a randomly generated state value (nonce) and store it so you can verify it in the next step. This prevents CSRF attacks.

Parameter	Description
`client_id`	Your app's client ID.
`scope`	A comma-separated list of access scopes your app needs. Some scopes grant access to protected customer data, which places additional requirements on your app.
`redirect_uri`	The URL Shopify redirects to after authorization. Must exactly match a redirect URI you've configured in the Dev Dashboard or your app's configuration TOML file.
`state`	A randomly generated nonce unique to this request.

/node/index.js

100

101

102

103

104

105

106

107

108

109

110

111

112

113

114

115

116

117

118

119

120

121

122

123

124

125

126

127

128

129

130

131

132

133

134

135

136

137

138

139

140

141

142

143

144

145

146

147

148

149

150

151

152

153

154

155

156

157

158

159

160

161

162

163

164

165

166

167

168

169

170

171

172

173

174

175

176

177

178

179

180

181

182

183

184

185

186

187

188

189

190

191

192

193

194

195

196

197

198

199

200

201

202

203

204

205

206

207

208

209

210

211

212

213

214

215

216

217

218

219

220

221

222

223

224

225

226

227

228

229

230

231

232

233

234

235

236

237

238

239

240

241

242

243

244

245

246

247

248

249

250

251

252

253

254

255

256

257

258

259

260

261

262

263

264

265

266

267

268

269

270

271

272

273

274

275

276

277

278

279

280

281

282

283

284

285

286

287

288

289

290

291

292

293

294

295

296

297

import express from 'express';

import crypto from 'crypto';

import cookieParser from 'cookie-parser';

import * as dotenv from 'dotenv';

dotenv.config();

// Falls back to a random secret for local dev. Set COOKIE_SECRET in production

// so signed cookies stay valid across restarts and deployments.

const COOKIE_SECRET = process.env.COOKIE_SECRET || crypto.randomBytes(64).toString('hex');

const app = express();

app.use(cookieParser(COOKIE_SECRET));

const CLIENT_ID = process.env.SHOPIFY_CLIENT_ID;

const CLIENT_SECRET = process.env.SHOPIFY_CLIENT_SECRET;

const REDIRECT_URI = process.env.REDIRECT_URI;

const SCOPES = process.env.SCOPES || 'read_products,write_orders';

// In-memory token store (use a database in production)

const tokenStore = {};

// Send cookies only over HTTPS in production; over plain HTTP on localhost in

// dev. httpOnly + sameSite protect them the rest of the time.

const cookieOptions = {

signed: true,

httpOnly: true,

sameSite: 'lax',

secure: process.env.NODE_ENV === 'production',

};

// A valid expiring-token response includes expires_in (seconds until the access

// token expires). Return null when it's absent or non-positive: treat the token

// as non-expiring and never refresh it. Storing Date.now() instead would make

// the next request refresh a token that has no refresh_token — a permanent 401.

function expiresAtFrom(expiresIn) {

const seconds = Number(expiresIn);

return seconds > 0 ? Date.now() + seconds * 1000 : null;

}

function isValidShopDomain(shop) {

return /^[a-zA-Z0-9][a-zA-Z0-9\-]*\.myshopify\.com$/.test(shop);

}

// Node's fetch has no timeout, so a stalled connection to Shopify would hang a

// request until the client gives up. Give every call a deadline, and tag transport

// failures so callers can tell "Shopify said no" from "we never reached Shopify".

// fetch rejects only on a transport failure or this timeout: every HTTP status,

// including 5xx, resolves and is the caller's to handle.

const SHOPIFY_TIMEOUT_MS = 30_000;

class ShopifyUnreachable extends Error {}

async function shopifyFetch(url, options) {

try {

return await fetch(url, {

...options,

signal: AbortSignal.timeout(SHOPIFY_TIMEOUT_MS),

});

} catch (cause) {

throw new ShopifyUnreachable(`Could not reach ${new URL(url).hostname}`, { cause });

}

app.get('/install', (req, res) => {

const { shop } = req.query;

if (!isValidShopDomain(shop)) {

return res.status(400).send('Invalid shop domain');

}

const nonce = crypto.randomBytes(16).toString('hex');

// Store the nonce in a signed cookie so you can verify it against the callback

res.cookie('oauth_state', nonce, cookieOptions);

const authUrl = `https://${shop}/admin/oauth/authorize?` +

new URLSearchParams({

client_id: CLIENT_ID,

scope: SCOPES,

redirect_uri: REDIRECT_URI,

state: nonce,

});

res.redirect(authUrl);

});

app.get('/callback', async (req, res) => {

const { code, hmac, shop, state } = req.query;

if (!state || state !== req.signedCookies.oauth_state) {

return res.status(403).send('Invalid state parameter');

}

res.clearCookie('oauth_state');

const params = Object.fromEntries(

Object.entries(req.query).filter(([key]) => key !== 'hmac')

);

const message = Object.entries(params).sort().map(([k, v]) => `${k}=${v}`).join('&');

const digest = crypto.createHmac('sha256', CLIENT_SECRET).update(message).digest('hex');

const digestBuf = Buffer.from(digest);

const hmacBuf = Buffer.from(String(hmac));

if (digestBuf.length !== hmacBuf.length || !crypto.timingSafeEqual(digestBuf, hmacBuf)) {

return res.status(403).send('Invalid HMAC');

}

if (!isValidShopDomain(shop)) {

return res.status(400).send('Invalid shop domain');

}

const tokenResponse = await shopifyFetch(`https://${shop}/admin/oauth/access_token`, {

method: 'POST',

headers: {

'Content-Type': 'application/x-www-form-urlencoded',

Accept: 'application/json',

body: new URLSearchParams({

client_id: CLIENT_ID,

client_secret: CLIENT_SECRET,

code,

expiring: '1',

}),

});

if (!tokenResponse.ok) {

return res.status(403).send('Token exchange failed');

}

const { access_token, refresh_token, scope, expires_in } = await tokenResponse.json();

const granted = scope.split(',');

// A write_* grant includes its matching read_* scope, so Shopify may return

// only the write scope. Treat a requested read_* as satisfied by its write_*.

const missing = SCOPES.split(',').filter(s =>

!granted.includes(s) &&

!(s.startsWith('read_') && granted.includes(`write_${s.slice(5)}`))

);

if (missing.length > 0) return res.status(403).send(`Missing scopes: ${missing.join(', ')}`);

// Store tokens server-side, keyed by shop (use a database in production).

// Track when the access token expires so requests can refresh it in time.

tokenStore[shop] = {

access_token,

refresh_token,

expires_at: expiresAtFrom(expires_in),

};

// Set a signed session cookie so subsequent requests can identify the shop

res.cookie('shop', shop, cookieOptions);

res.json({ message: 'App installed', shop, scope });

});

// Exchange the stored refresh token for a new access token. The return value

// tells the caller how to react, and matches the refresh error handling used

// across grant types:

// 'refreshed' — got a new access token

// 'reauthorize' — a 401 means the refresh token is terminal (expired, revoked,

// replayed after the one-hour retry window, or the app was

// uninstalled); send the merchant back through OAuth

// 'retry' — a transient failure (network, timeout, 5xx, 429); safe to

// retry later with the same refresh token

// 'failed' — any other non-OK status, such as a malformed request or bad

// client credentials; retrying sends the identical request and

// fails the same way, so surface it instead of hiding it

async function refreshAccessToken(shop) {

const stored = tokenStore[shop];

if (!stored?.refresh_token) return 'reauthorize';

let response;

try {

response = await shopifyFetch(`https://${shop}/admin/oauth/access_token`, {

method: 'POST',

headers: {

'Content-Type': 'application/x-www-form-urlencoded',

Accept: 'application/json',

body: new URLSearchParams({

client_id: CLIENT_ID,

client_secret: CLIENT_SECRET,

grant_type: 'refresh_token',

refresh_token: stored.refresh_token,

}),

});

} catch (error) {

// Only a transport failure or timeout becomes 'retry': the request never

// reached Shopify, so the refresh token is untouched and a later attempt is

// safe. Anything else is a bug in this code — let it surface.

if (!(error instanceof ShopifyUnreachable)) throw error;

return 'retry';

}

// A 401 is terminal: drop the dead token so the merchant reinstalls.

if (response.status === 401) {

delete tokenStore[shop];

return 'reauthorize';

}

// Only a rate limit or a server fault is worth retrying. Treating every other

// non-OK status as transient would retry an unrecoverable refresh forever —

// a 400 for a malformed body, or a 403 for bad client credentials, returns the

// same response no matter how long you wait.

if (response.status === 429 || response.status >= 500) return 'retry';

if (!response.ok) return 'failed';

const { access_token, refresh_token, expires_in } = await response.json();

tokenStore[shop] = {

access_token,

refresh_token,

expires_at: expiresAtFrom(expires_in),

};

return 'refreshed';

}

app.get('/products', async (req, res) => {

const shop = req.signedCookies.shop;

if (!shop) return res.status(401).send('Not authenticated');

let stored = tokenStore[shop];

if (!stored) return res.status(401).send('Not authenticated');

// Expiring access tokens are short-lived. Refresh ~60 seconds before the token

// actually expires so a request never goes out with a token that lapses

// mid-flight.

if (stored.expires_at && Date.now() >= stored.expires_at - 60 * 1000) {

const result = await refreshAccessToken(shop);

if (result === 'reauthorize') {

return res.status(401).send('Reauthorization required');

}

if (result === 'retry') {

return res.status(503).send('Token refresh failed, try again');

}

if (result === 'failed') {

// Not the merchant's problem and not worth retrying: fix the app's request

// or credentials. Don't fall through — `stored` still holds the token that

// is about to expire.

return res.status(502).send('Token refresh failed');

}

stored = tokenStore[shop];

}

const callAdminApi = (accessToken) =>

shopifyFetch(`https://${shop}/admin/api/2026-04/graphql.json`, {

method: 'POST',

headers: {

'Content-Type': 'application/json',

'X-Shopify-Access-Token': accessToken,

body: JSON.stringify({ query: '{ products(first: 5) { edges { node { id handle } } } }' }),

});

let response = await callAdminApi(stored.access_token);

// Shopify rejected the access token: it was revoked, the app's access scopes

// changed, or it lapsed sooner than expires_in implied. This app runs outside

// the Shopify admin, so it has no ID token to exchange — the refresh token is

// the only way back. Try it once, then give up rather than sending the same

// rejected token again on every later request.

if (response.status === 401) {

const result = await refreshAccessToken(shop);

if (result === 'retry') {

// Transient: the refresh token is untouched, so a later attempt is fine.

return res.status(503).send('Token refresh failed, try again');

}

if (result === 'failed') {

return res.status(502).send('Token refresh failed');

}

if (result !== 'refreshed') {

// Drop the rejected token so the next request doesn't send it again.

delete tokenStore[shop];

return res.status(401).send('Reauthorization required');

}

response = await callAdminApi(tokenStore[shop].access_token);

// Retry once, not in a loop. A freshly refreshed token that's also rejected

// means something is wrong beyond a lapsed credential, so stop and send the

// merchant back through OAuth.

if (response.status === 401) {

delete tokenStore[shop];

return res.status(401).send('Reauthorization required');

}

// Forward Shopify's status. Answering a rate limit or an outage with a 200 and

// an error body in it would tell the client the request succeeded.

res.status(response.status).json(await response.json());

});

// The routes above let a transport failure or timeout propagate. The request never

// reached Shopify, so nothing was consumed and the caller can try again: 503 says

// that, while the stack trace Express would otherwise return says the app is broken.

app.use((err, req, res, next) => {

if (err instanceof ShopifyUnreachable) {

return res.status(503).send('Could not reach Shopify, try again');

}

next(err);

});

app.listen(3000, () => console.log('Server running on http://localhost:3000'));

Anchor to Validate the callbackValidate the callback

After the merchant approves your app, Shopify redirects to your redirect_uri with an authorization code and several query parameters. Validate all of them before exchanging the code.

https://your-app.example.com/callback?code={authorization_code}&hmac={hmac}&shop={shop}&state={nonce}&timestamp={timestamp}

Anchor to Verify the ,[object Object], parameterVerify the `state` parameter

Compare the state parameter to the nonce you stored in step 1. If they don't match, reject the request.

/node/index.js

100

101

102

103

104

105

106

107

108

109

110

111

112

113

114

115

116

117

118

119

120

121

122

123

124

125

126

127

128

129

130

131

132

133

134

135

136

137

138

139

140

141

142

143

144

145

146

147

148

149

150

151

152

153

154

155

156

157

158

159

160

161

162

163

164

165

166

167

168

169

170

171

172

173

174

175

176

177

178

179

180

181

182

183

184

185

186

187

188

189

190

191

192

193

194

195

196

197

198

199

200

201

202

203

204

205

206

207

208

209

210

211

212

213

214

215

216

217

218

219

220

221

222

223

224

225

226

227

228

229

230

231

232

233

234

235

236

237

238

239

240

241

242

243

244

245

246

247

248

249

250

251

252

253

254

255

256

257

258

259

260

261

262

263

264

265

266

267

268

269

270

271

272

273

274

275

276

277

278

279

280

281

282

283

284

285

286

287

288

289

290

291

292

293

294

295

296

297

import express from 'express';

import crypto from 'crypto';

import cookieParser from 'cookie-parser';

import * as dotenv from 'dotenv';

dotenv.config();

// Falls back to a random secret for local dev. Set COOKIE_SECRET in production

// so signed cookies stay valid across restarts and deployments.

const COOKIE_SECRET = process.env.COOKIE_SECRET || crypto.randomBytes(64).toString('hex');

const app = express();

app.use(cookieParser(COOKIE_SECRET));

const CLIENT_ID = process.env.SHOPIFY_CLIENT_ID;

const CLIENT_SECRET = process.env.SHOPIFY_CLIENT_SECRET;

const REDIRECT_URI = process.env.REDIRECT_URI;

const SCOPES = process.env.SCOPES || 'read_products,write_orders';

// In-memory token store (use a database in production)

const tokenStore = {};

// Send cookies only over HTTPS in production; over plain HTTP on localhost in

// dev. httpOnly + sameSite protect them the rest of the time.

const cookieOptions = {

signed: true,

httpOnly: true,

sameSite: 'lax',

secure: process.env.NODE_ENV === 'production',

};

// A valid expiring-token response includes expires_in (seconds until the access

// token expires). Return null when it's absent or non-positive: treat the token

// as non-expiring and never refresh it. Storing Date.now() instead would make

// the next request refresh a token that has no refresh_token — a permanent 401.

function expiresAtFrom(expiresIn) {

const seconds = Number(expiresIn);

return seconds > 0 ? Date.now() + seconds * 1000 : null;

}

function isValidShopDomain(shop) {

return /^[a-zA-Z0-9][a-zA-Z0-9\-]*\.myshopify\.com$/.test(shop);

}

// Node's fetch has no timeout, so a stalled connection to Shopify would hang a

// request until the client gives up. Give every call a deadline, and tag transport

// failures so callers can tell "Shopify said no" from "we never reached Shopify".

// fetch rejects only on a transport failure or this timeout: every HTTP status,

// including 5xx, resolves and is the caller's to handle.

const SHOPIFY_TIMEOUT_MS = 30_000;

class ShopifyUnreachable extends Error {}

async function shopifyFetch(url, options) {

try {

return await fetch(url, {

...options,

signal: AbortSignal.timeout(SHOPIFY_TIMEOUT_MS),

});

} catch (cause) {

throw new ShopifyUnreachable(`Could not reach ${new URL(url).hostname}`, { cause });

}

app.get('/install', (req, res) => {

const { shop } = req.query;

if (!isValidShopDomain(shop)) {

return res.status(400).send('Invalid shop domain');

}

const nonce = crypto.randomBytes(16).toString('hex');

// Store the nonce in a signed cookie so you can verify it against the callback

res.cookie('oauth_state', nonce, cookieOptions);

const authUrl = `https://${shop}/admin/oauth/authorize?` +

new URLSearchParams({

client_id: CLIENT_ID,

scope: SCOPES,

redirect_uri: REDIRECT_URI,

state: nonce,

});

res.redirect(authUrl);

});

app.get('/callback', async (req, res) => {

const { code, hmac, shop, state } = req.query;

if (!state || state !== req.signedCookies.oauth_state) {

return res.status(403).send('Invalid state parameter');

}

res.clearCookie('oauth_state');

const params = Object.fromEntries(

Object.entries(req.query).filter(([key]) => key !== 'hmac')

);

const message = Object.entries(params).sort().map(([k, v]) => `${k}=${v}`).join('&');

const digest = crypto.createHmac('sha256', CLIENT_SECRET).update(message).digest('hex');

const digestBuf = Buffer.from(digest);

const hmacBuf = Buffer.from(String(hmac));

if (digestBuf.length !== hmacBuf.length || !crypto.timingSafeEqual(digestBuf, hmacBuf)) {

return res.status(403).send('Invalid HMAC');

}

if (!isValidShopDomain(shop)) {

return res.status(400).send('Invalid shop domain');

}

const tokenResponse = await shopifyFetch(`https://${shop}/admin/oauth/access_token`, {

method: 'POST',

headers: {

'Content-Type': 'application/x-www-form-urlencoded',

Accept: 'application/json',

body: new URLSearchParams({

client_id: CLIENT_ID,

client_secret: CLIENT_SECRET,

code,

expiring: '1',

}),

});

if (!tokenResponse.ok) {

return res.status(403).send('Token exchange failed');

}

const { access_token, refresh_token, scope, expires_in } = await tokenResponse.json();

const granted = scope.split(',');

// A write_* grant includes its matching read_* scope, so Shopify may return

// only the write scope. Treat a requested read_* as satisfied by its write_*.

const missing = SCOPES.split(',').filter(s =>

!granted.includes(s) &&

!(s.startsWith('read_') && granted.includes(`write_${s.slice(5)}`))

);

if (missing.length > 0) return res.status(403).send(`Missing scopes: ${missing.join(', ')}`);

// Store tokens server-side, keyed by shop (use a database in production).

// Track when the access token expires so requests can refresh it in time.

tokenStore[shop] = {

access_token,

refresh_token,

expires_at: expiresAtFrom(expires_in),

};

// Set a signed session cookie so subsequent requests can identify the shop

res.cookie('shop', shop, cookieOptions);

res.json({ message: 'App installed', shop, scope });

});

// Exchange the stored refresh token for a new access token. The return value

// tells the caller how to react, and matches the refresh error handling used

// across grant types:

// 'refreshed' — got a new access token

// 'reauthorize' — a 401 means the refresh token is terminal (expired, revoked,

// replayed after the one-hour retry window, or the app was

// uninstalled); send the merchant back through OAuth

// 'retry' — a transient failure (network, timeout, 5xx, 429); safe to

// retry later with the same refresh token

// 'failed' — any other non-OK status, such as a malformed request or bad

// client credentials; retrying sends the identical request and

// fails the same way, so surface it instead of hiding it

async function refreshAccessToken(shop) {

const stored = tokenStore[shop];

if (!stored?.refresh_token) return 'reauthorize';

let response;

try {

response = await shopifyFetch(`https://${shop}/admin/oauth/access_token`, {

method: 'POST',

headers: {

'Content-Type': 'application/x-www-form-urlencoded',

Accept: 'application/json',

body: new URLSearchParams({

client_id: CLIENT_ID,

client_secret: CLIENT_SECRET,

grant_type: 'refresh_token',

refresh_token: stored.refresh_token,

}),

});

} catch (error) {

// Only a transport failure or timeout becomes 'retry': the request never

// reached Shopify, so the refresh token is untouched and a later attempt is

// safe. Anything else is a bug in this code — let it surface.

if (!(error instanceof ShopifyUnreachable)) throw error;

return 'retry';

}

// A 401 is terminal: drop the dead token so the merchant reinstalls.

if (response.status === 401) {

delete tokenStore[shop];

return 'reauthorize';

}

// Only a rate limit or a server fault is worth retrying. Treating every other

// non-OK status as transient would retry an unrecoverable refresh forever —

// a 400 for a malformed body, or a 403 for bad client credentials, returns the

// same response no matter how long you wait.

if (response.status === 429 || response.status >= 500) return 'retry';

if (!response.ok) return 'failed';

const { access_token, refresh_token, expires_in } = await response.json();

tokenStore[shop] = {

access_token,

refresh_token,

expires_at: expiresAtFrom(expires_in),

};

return 'refreshed';

}

app.get('/products', async (req, res) => {

const shop = req.signedCookies.shop;

if (!shop) return res.status(401).send('Not authenticated');

let stored = tokenStore[shop];

if (!stored) return res.status(401).send('Not authenticated');

// Expiring access tokens are short-lived. Refresh ~60 seconds before the token

// actually expires so a request never goes out with a token that lapses

// mid-flight.

if (stored.expires_at && Date.now() >= stored.expires_at - 60 * 1000) {

const result = await refreshAccessToken(shop);

if (result === 'reauthorize') {

return res.status(401).send('Reauthorization required');

}

if (result === 'retry') {

return res.status(503).send('Token refresh failed, try again');

}

if (result === 'failed') {

// Not the merchant's problem and not worth retrying: fix the app's request

// or credentials. Don't fall through — `stored` still holds the token that

// is about to expire.

return res.status(502).send('Token refresh failed');

}

stored = tokenStore[shop];

}

const callAdminApi = (accessToken) =>

shopifyFetch(`https://${shop}/admin/api/2026-04/graphql.json`, {

method: 'POST',

headers: {

'Content-Type': 'application/json',

'X-Shopify-Access-Token': accessToken,

body: JSON.stringify({ query: '{ products(first: 5) { edges { node { id handle } } } }' }),

});

let response = await callAdminApi(stored.access_token);

// Shopify rejected the access token: it was revoked, the app's access scopes

// changed, or it lapsed sooner than expires_in implied. This app runs outside

// the Shopify admin, so it has no ID token to exchange — the refresh token is

// the only way back. Try it once, then give up rather than sending the same

// rejected token again on every later request.

if (response.status === 401) {

const result = await refreshAccessToken(shop);

if (result === 'retry') {

// Transient: the refresh token is untouched, so a later attempt is fine.

return res.status(503).send('Token refresh failed, try again');

}

if (result === 'failed') {

return res.status(502).send('Token refresh failed');

}

if (result !== 'refreshed') {

// Drop the rejected token so the next request doesn't send it again.

delete tokenStore[shop];

return res.status(401).send('Reauthorization required');

}

response = await callAdminApi(tokenStore[shop].access_token);

// Retry once, not in a loop. A freshly refreshed token that's also rejected

// means something is wrong beyond a lapsed credential, so stop and send the

// merchant back through OAuth.

if (response.status === 401) {

delete tokenStore[shop];

return res.status(401).send('Reauthorization required');

}

// Forward Shopify's status. Answering a rate limit or an outage with a 200 and

// an error body in it would tell the client the request succeeded.

res.status(response.status).json(await response.json());

});

// The routes above let a transport failure or timeout propagate. The request never

// reached Shopify, so nothing was consumed and the caller can try again: 503 says

// that, while the stack trace Express would otherwise return says the app is broken.

app.use((err, req, res, next) => {

if (err instanceof ShopifyUnreachable) {

return res.status(503).send('Could not reach Shopify, try again');

}

next(err);

});

app.listen(3000, () => console.log('Server running on http://localhost:3000'));

Anchor to Verify the HMACVerify the HMAC

Remove the hmac parameter from the query string, sort the remaining parameters alphabetically, and compute an HMAC-SHA256 hash using your client secret. The result must match the hmac value. Use a constant-time comparison, such as crypto.timingSafeEqual in Node.js or hmac.compare_digest in Python, so the check doesn't leak timing information.

If you're using one of Shopify's API libraries, these checks are built in:

/node/index.js

100

101

102

103

104

105

106

107

108

109

110

111

112

113

114

115

116

117

118

119

120

121

122

123

124

125

126

127

128

129

130

131

132

133

134

135

136

137

138

139

140

141

142

143

144

145

146

147

148

149

150

151

152

153

154

155

156

157

158

159

160

161

162

163

164

165

166

167

168

169

170

171

172

173

174

175

176

177

178

179

180

181

182

183

184

185

186

187

188

189

190

191

192

193

194

195

196

197

198

199

200

201

202

203

204

205

206

207

208

209

210

211

212

213

214

215

216

217

218

219

220

221

222

223

224

225

226

227

228

229

230

231

232

233

234

235

236

237

238

239

240

241

242

243

244

245

246

247

248

249

250

251

252

253

254

255

256

257

258

259

260

261

262

263

264

265

266

267

268

269

270

271

272

273

274

275

276

277

278

279

280

281

282

283

284

285

286

287

288

289

290

291

292

293

294

295

296

297

import express from 'express';

import crypto from 'crypto';

import cookieParser from 'cookie-parser';

import * as dotenv from 'dotenv';

dotenv.config();

// Falls back to a random secret for local dev. Set COOKIE_SECRET in production

// so signed cookies stay valid across restarts and deployments.

const COOKIE_SECRET = process.env.COOKIE_SECRET || crypto.randomBytes(64).toString('hex');

const app = express();

app.use(cookieParser(COOKIE_SECRET));

const CLIENT_ID = process.env.SHOPIFY_CLIENT_ID;

const CLIENT_SECRET = process.env.SHOPIFY_CLIENT_SECRET;

const REDIRECT_URI = process.env.REDIRECT_URI;

const SCOPES = process.env.SCOPES || 'read_products,write_orders';

// In-memory token store (use a database in production)

const tokenStore = {};

// Send cookies only over HTTPS in production; over plain HTTP on localhost in

// dev. httpOnly + sameSite protect them the rest of the time.

const cookieOptions = {

signed: true,

httpOnly: true,

sameSite: 'lax',

secure: process.env.NODE_ENV === 'production',

};

// A valid expiring-token response includes expires_in (seconds until the access

// token expires). Return null when it's absent or non-positive: treat the token

// as non-expiring and never refresh it. Storing Date.now() instead would make

// the next request refresh a token that has no refresh_token — a permanent 401.

function expiresAtFrom(expiresIn) {

const seconds = Number(expiresIn);

return seconds > 0 ? Date.now() + seconds * 1000 : null;

}

function isValidShopDomain(shop) {

return /^[a-zA-Z0-9][a-zA-Z0-9\-]*\.myshopify\.com$/.test(shop);

}

// Node's fetch has no timeout, so a stalled connection to Shopify would hang a

// request until the client gives up. Give every call a deadline, and tag transport

// failures so callers can tell "Shopify said no" from "we never reached Shopify".

// fetch rejects only on a transport failure or this timeout: every HTTP status,

// including 5xx, resolves and is the caller's to handle.

const SHOPIFY_TIMEOUT_MS = 30_000;

class ShopifyUnreachable extends Error {}

async function shopifyFetch(url, options) {

try {

return await fetch(url, {

...options,

signal: AbortSignal.timeout(SHOPIFY_TIMEOUT_MS),

});

} catch (cause) {

throw new ShopifyUnreachable(`Could not reach ${new URL(url).hostname}`, { cause });

}

app.get('/install', (req, res) => {

const { shop } = req.query;

if (!isValidShopDomain(shop)) {

return res.status(400).send('Invalid shop domain');

}

const nonce = crypto.randomBytes(16).toString('hex');

// Store the nonce in a signed cookie so you can verify it against the callback

res.cookie('oauth_state', nonce, cookieOptions);

const authUrl = `https://${shop}/admin/oauth/authorize?` +

new URLSearchParams({

client_id: CLIENT_ID,

scope: SCOPES,

redirect_uri: REDIRECT_URI,

state: nonce,

});

res.redirect(authUrl);

});

app.get('/callback', async (req, res) => {

const { code, hmac, shop, state } = req.query;

if (!state || state !== req.signedCookies.oauth_state) {

return res.status(403).send('Invalid state parameter');

}

res.clearCookie('oauth_state');

const params = Object.fromEntries(

Object.entries(req.query).filter(([key]) => key !== 'hmac')

);

  const message = Object.entries(params).sort().map(([k, v]) => `${k}=${v}`).join('&');

  const digest = crypto.createHmac('sha256', CLIENT_SECRET).update(message).digest('hex');

const digestBuf = Buffer.from(digest);

const hmacBuf = Buffer.from(String(hmac));

  if (digestBuf.length !== hmacBuf.length || !crypto.timingSafeEqual(digestBuf, hmacBuf)) {

return res.status(403).send('Invalid HMAC');

}

if (!isValidShopDomain(shop)) {

return res.status(400).send('Invalid shop domain');

}

const tokenResponse = await shopifyFetch(`https://${shop}/admin/oauth/access_token`, {

method: 'POST',

headers: {

'Content-Type': 'application/x-www-form-urlencoded',

Accept: 'application/json',

body: new URLSearchParams({

client_id: CLIENT_ID,

client_secret: CLIENT_SECRET,

code,

expiring: '1',

}),

});

if (!tokenResponse.ok) {

return res.status(403).send('Token exchange failed');

}

const { access_token, refresh_token, scope, expires_in } = await tokenResponse.json();

const granted = scope.split(',');

// A write_* grant includes its matching read_* scope, so Shopify may return

// only the write scope. Treat a requested read_* as satisfied by its write_*.

const missing = SCOPES.split(',').filter(s =>

!granted.includes(s) &&

!(s.startsWith('read_') && granted.includes(`write_${s.slice(5)}`))

);

if (missing.length > 0) return res.status(403).send(`Missing scopes: ${missing.join(', ')}`);

// Store tokens server-side, keyed by shop (use a database in production).

// Track when the access token expires so requests can refresh it in time.

tokenStore[shop] = {

access_token,

refresh_token,

expires_at: expiresAtFrom(expires_in),

};

// Set a signed session cookie so subsequent requests can identify the shop

res.cookie('shop', shop, cookieOptions);

res.json({ message: 'App installed', shop, scope });

});

// Exchange the stored refresh token for a new access token. The return value

// tells the caller how to react, and matches the refresh error handling used

// across grant types:

// 'refreshed' — got a new access token

// 'reauthorize' — a 401 means the refresh token is terminal (expired, revoked,

// replayed after the one-hour retry window, or the app was

// uninstalled); send the merchant back through OAuth

// 'retry' — a transient failure (network, timeout, 5xx, 429); safe to

// retry later with the same refresh token

// 'failed' — any other non-OK status, such as a malformed request or bad

// client credentials; retrying sends the identical request and

// fails the same way, so surface it instead of hiding it

async function refreshAccessToken(shop) {

const stored = tokenStore[shop];

if (!stored?.refresh_token) return 'reauthorize';

let response;

try {

response = await shopifyFetch(`https://${shop}/admin/oauth/access_token`, {

method: 'POST',

headers: {

'Content-Type': 'application/x-www-form-urlencoded',

Accept: 'application/json',

body: new URLSearchParams({

client_id: CLIENT_ID,

client_secret: CLIENT_SECRET,

grant_type: 'refresh_token',

refresh_token: stored.refresh_token,

}),

});

} catch (error) {

// Only a transport failure or timeout becomes 'retry': the request never

// reached Shopify, so the refresh token is untouched and a later attempt is

// safe. Anything else is a bug in this code — let it surface.

if (!(error instanceof ShopifyUnreachable)) throw error;

return 'retry';

}

// A 401 is terminal: drop the dead token so the merchant reinstalls.

if (response.status === 401) {

delete tokenStore[shop];

return 'reauthorize';

}

// Only a rate limit or a server fault is worth retrying. Treating every other

// non-OK status as transient would retry an unrecoverable refresh forever —

// a 400 for a malformed body, or a 403 for bad client credentials, returns the

// same response no matter how long you wait.

if (response.status === 429 || response.status >= 500) return 'retry';

if (!response.ok) return 'failed';

const { access_token, refresh_token, expires_in } = await response.json();

tokenStore[shop] = {

access_token,

refresh_token,

expires_at: expiresAtFrom(expires_in),

};

return 'refreshed';

}

app.get('/products', async (req, res) => {

const shop = req.signedCookies.shop;

if (!shop) return res.status(401).send('Not authenticated');

let stored = tokenStore[shop];

if (!stored) return res.status(401).send('Not authenticated');

// Expiring access tokens are short-lived. Refresh ~60 seconds before the token

// actually expires so a request never goes out with a token that lapses

// mid-flight.

if (stored.expires_at && Date.now() >= stored.expires_at - 60 * 1000) {

const result = await refreshAccessToken(shop);

if (result === 'reauthorize') {

return res.status(401).send('Reauthorization required');

}

if (result === 'retry') {

return res.status(503).send('Token refresh failed, try again');

}

if (result === 'failed') {

// Not the merchant's problem and not worth retrying: fix the app's request

// or credentials. Don't fall through — `stored` still holds the token that

// is about to expire.

return res.status(502).send('Token refresh failed');

}

stored = tokenStore[shop];

}

const callAdminApi = (accessToken) =>

shopifyFetch(`https://${shop}/admin/api/2026-04/graphql.json`, {

method: 'POST',

headers: {

'Content-Type': 'application/json',

'X-Shopify-Access-Token': accessToken,

body: JSON.stringify({ query: '{ products(first: 5) { edges { node { id handle } } } }' }),

});

let response = await callAdminApi(stored.access_token);

// Shopify rejected the access token: it was revoked, the app's access scopes

// changed, or it lapsed sooner than expires_in implied. This app runs outside

// the Shopify admin, so it has no ID token to exchange — the refresh token is

// the only way back. Try it once, then give up rather than sending the same

// rejected token again on every later request.

if (response.status === 401) {

const result = await refreshAccessToken(shop);

if (result === 'retry') {

// Transient: the refresh token is untouched, so a later attempt is fine.

return res.status(503).send('Token refresh failed, try again');

}

if (result === 'failed') {

return res.status(502).send('Token refresh failed');

}

if (result !== 'refreshed') {

// Drop the rejected token so the next request doesn't send it again.

delete tokenStore[shop];

return res.status(401).send('Reauthorization required');

}

response = await callAdminApi(tokenStore[shop].access_token);

// Retry once, not in a loop. A freshly refreshed token that's also rejected

// means something is wrong beyond a lapsed credential, so stop and send the

// merchant back through OAuth.

if (response.status === 401) {

delete tokenStore[shop];

return res.status(401).send('Reauthorization required');

}

// Forward Shopify's status. Answering a rate limit or an outage with a 200 and

// an error body in it would tell the client the request succeeded.

res.status(response.status).json(await response.json());

});

// The routes above let a transport failure or timeout propagate. The request never

// reached Shopify, so nothing was consumed and the caller can try again: 503 says

// that, while the stack trace Express would otherwise return says the app is broken.

app.use((err, req, res, next) => {

if (err instanceof ShopifyUnreachable) {

return res.status(503).send('Could not reach Shopify, try again');

}

next(err);

});

app.listen(3000, () => console.log('Server running on http://localhost:3000'));

Anchor to Validate the ,[object Object], domainValidate the `shop` domain

Confirm the shop parameter matches ^[a-zA-Z0-9][a-zA-Z0-9\-]*\.myshopify\.com$. Anchor the pattern at both ends. Without the trailing $, a value such as exampleshop.myshopify.com.attacker.example passes the check, and your app sends the authorization code to a host you don't control.

/node/index.js

100

101

102

103

104

105

106

107

108

109

110

111

112

113

114

115

116

117

118

119

120

121

122

123

124

125

126

127

128

129

130

131

132

133

134

135

136

137

138

139

140

141

142

143

144

145

146

147

148

149

150

151

152

153

154

155

156

157

158

159

160

161

162

163

164

165

166

167

168

169

170

171

172

173

174

175

176

177

178

179

180

181

182

183

184

185

186

187

188

189

190

191

192

193

194

195

196

197

198

199

200

201

202

203

204

205

206

207

208

209

210

211

212

213

214

215

216

217

218

219

220

221

222

223

224

225

226

227

228

229

230

231

232

233

234

235

236

237

238

239

240

241

242

243

244

245

246

247

248

249

250

251

252

253

254

255

256

257

258

259

260

261

262

263

264

265

266

267

268

269

270

271

272

273

274

275

276

277

278

279

280

281

282

283

284

285

286

287

288

289

290

291

292

293

294

295

296

297

import express from 'express';

import crypto from 'crypto';

import cookieParser from 'cookie-parser';

import * as dotenv from 'dotenv';

dotenv.config();

// Falls back to a random secret for local dev. Set COOKIE_SECRET in production

// so signed cookies stay valid across restarts and deployments.

const COOKIE_SECRET = process.env.COOKIE_SECRET || crypto.randomBytes(64).toString('hex');

const app = express();

app.use(cookieParser(COOKIE_SECRET));

const CLIENT_ID = process.env.SHOPIFY_CLIENT_ID;

const CLIENT_SECRET = process.env.SHOPIFY_CLIENT_SECRET;

const REDIRECT_URI = process.env.REDIRECT_URI;

const SCOPES = process.env.SCOPES || 'read_products,write_orders';

// In-memory token store (use a database in production)

const tokenStore = {};

// Send cookies only over HTTPS in production; over plain HTTP on localhost in

// dev. httpOnly + sameSite protect them the rest of the time.

const cookieOptions = {

signed: true,

httpOnly: true,

sameSite: 'lax',

secure: process.env.NODE_ENV === 'production',

};

// A valid expiring-token response includes expires_in (seconds until the access

// token expires). Return null when it's absent or non-positive: treat the token

// as non-expiring and never refresh it. Storing Date.now() instead would make

// the next request refresh a token that has no refresh_token — a permanent 401.

function expiresAtFrom(expiresIn) {

const seconds = Number(expiresIn);

return seconds > 0 ? Date.now() + seconds * 1000 : null;

}

function isValidShopDomain(shop) {

return /^[a-zA-Z0-9][a-zA-Z0-9\-]*\.myshopify\.com$/.test(shop);

}

// Node's fetch has no timeout, so a stalled connection to Shopify would hang a

// request until the client gives up. Give every call a deadline, and tag transport

// failures so callers can tell "Shopify said no" from "we never reached Shopify".

// fetch rejects only on a transport failure or this timeout: every HTTP status,

// including 5xx, resolves and is the caller's to handle.

const SHOPIFY_TIMEOUT_MS = 30_000;

class ShopifyUnreachable extends Error {}

async function shopifyFetch(url, options) {

try {

return await fetch(url, {

...options,

signal: AbortSignal.timeout(SHOPIFY_TIMEOUT_MS),

});

} catch (cause) {

throw new ShopifyUnreachable(`Could not reach ${new URL(url).hostname}`, { cause });

}

app.get('/install', (req, res) => {

const { shop } = req.query;

if (!isValidShopDomain(shop)) {

return res.status(400).send('Invalid shop domain');

}

const nonce = crypto.randomBytes(16).toString('hex');

// Store the nonce in a signed cookie so you can verify it against the callback

res.cookie('oauth_state', nonce, cookieOptions);

const authUrl = `https://${shop}/admin/oauth/authorize?` +

new URLSearchParams({

client_id: CLIENT_ID,

scope: SCOPES,

redirect_uri: REDIRECT_URI,

state: nonce,

});

res.redirect(authUrl);

});

app.get('/callback', async (req, res) => {

const { code, hmac, shop, state } = req.query;

if (!state || state !== req.signedCookies.oauth_state) {

return res.status(403).send('Invalid state parameter');

}

res.clearCookie('oauth_state');

const params = Object.fromEntries(

Object.entries(req.query).filter(([key]) => key !== 'hmac')

);

const message = Object.entries(params).sort().map(([k, v]) => `${k}=${v}`).join('&');

const digest = crypto.createHmac('sha256', CLIENT_SECRET).update(message).digest('hex');

const digestBuf = Buffer.from(digest);

const hmacBuf = Buffer.from(String(hmac));

if (digestBuf.length !== hmacBuf.length || !crypto.timingSafeEqual(digestBuf, hmacBuf)) {

return res.status(403).send('Invalid HMAC');

}

if (!isValidShopDomain(shop)) {

return res.status(400).send('Invalid shop domain');

}

const tokenResponse = await shopifyFetch(`https://${shop}/admin/oauth/access_token`, {

method: 'POST',

headers: {

'Content-Type': 'application/x-www-form-urlencoded',

Accept: 'application/json',

body: new URLSearchParams({

client_id: CLIENT_ID,

client_secret: CLIENT_SECRET,

code,

expiring: '1',

}),

});

if (!tokenResponse.ok) {

return res.status(403).send('Token exchange failed');

}

const { access_token, refresh_token, scope, expires_in } = await tokenResponse.json();

const granted = scope.split(',');

// A write_* grant includes its matching read_* scope, so Shopify may return

// only the write scope. Treat a requested read_* as satisfied by its write_*.

const missing = SCOPES.split(',').filter(s =>

!granted.includes(s) &&

!(s.startsWith('read_') && granted.includes(`write_${s.slice(5)}`))

);

if (missing.length > 0) return res.status(403).send(`Missing scopes: ${missing.join(', ')}`);

// Store tokens server-side, keyed by shop (use a database in production).

// Track when the access token expires so requests can refresh it in time.

tokenStore[shop] = {

access_token,

refresh_token,

expires_at: expiresAtFrom(expires_in),

};

// Set a signed session cookie so subsequent requests can identify the shop

res.cookie('shop', shop, cookieOptions);

res.json({ message: 'App installed', shop, scope });

});

// Exchange the stored refresh token for a new access token. The return value

// tells the caller how to react, and matches the refresh error handling used

// across grant types:

// 'refreshed' — got a new access token

// 'reauthorize' — a 401 means the refresh token is terminal (expired, revoked,

// replayed after the one-hour retry window, or the app was

// uninstalled); send the merchant back through OAuth

// 'retry' — a transient failure (network, timeout, 5xx, 429); safe to

// retry later with the same refresh token

// 'failed' — any other non-OK status, such as a malformed request or bad

// client credentials; retrying sends the identical request and

// fails the same way, so surface it instead of hiding it

async function refreshAccessToken(shop) {

const stored = tokenStore[shop];

if (!stored?.refresh_token) return 'reauthorize';

let response;

try {

response = await shopifyFetch(`https://${shop}/admin/oauth/access_token`, {

method: 'POST',

headers: {

'Content-Type': 'application/x-www-form-urlencoded',

Accept: 'application/json',

body: new URLSearchParams({

client_id: CLIENT_ID,

client_secret: CLIENT_SECRET,

grant_type: 'refresh_token',

refresh_token: stored.refresh_token,

}),

});

} catch (error) {

// Only a transport failure or timeout becomes 'retry': the request never

// reached Shopify, so the refresh token is untouched and a later attempt is

// safe. Anything else is a bug in this code — let it surface.

if (!(error instanceof ShopifyUnreachable)) throw error;

return 'retry';

}

// A 401 is terminal: drop the dead token so the merchant reinstalls.

if (response.status === 401) {

delete tokenStore[shop];

return 'reauthorize';

}

// Only a rate limit or a server fault is worth retrying. Treating every other

// non-OK status as transient would retry an unrecoverable refresh forever —

// a 400 for a malformed body, or a 403 for bad client credentials, returns the

// same response no matter how long you wait.

if (response.status === 429 || response.status >= 500) return 'retry';

if (!response.ok) return 'failed';

const { access_token, refresh_token, expires_in } = await response.json();

tokenStore[shop] = {

access_token,

refresh_token,

expires_at: expiresAtFrom(expires_in),

};

return 'refreshed';

}

app.get('/products', async (req, res) => {

const shop = req.signedCookies.shop;

if (!shop) return res.status(401).send('Not authenticated');

let stored = tokenStore[shop];

if (!stored) return res.status(401).send('Not authenticated');

// Expiring access tokens are short-lived. Refresh ~60 seconds before the token

// actually expires so a request never goes out with a token that lapses

// mid-flight.

if (stored.expires_at && Date.now() >= stored.expires_at - 60 * 1000) {

const result = await refreshAccessToken(shop);

if (result === 'reauthorize') {

return res.status(401).send('Reauthorization required');

}

if (result === 'retry') {

return res.status(503).send('Token refresh failed, try again');

}

if (result === 'failed') {

// Not the merchant's problem and not worth retrying: fix the app's request

// or credentials. Don't fall through — `stored` still holds the token that

// is about to expire.

return res.status(502).send('Token refresh failed');

}

stored = tokenStore[shop];

}

const callAdminApi = (accessToken) =>

shopifyFetch(`https://${shop}/admin/api/2026-04/graphql.json`, {

method: 'POST',

headers: {

'Content-Type': 'application/json',

'X-Shopify-Access-Token': accessToken,

body: JSON.stringify({ query: '{ products(first: 5) { edges { node { id handle } } } }' }),

});

let response = await callAdminApi(stored.access_token);

// Shopify rejected the access token: it was revoked, the app's access scopes

// changed, or it lapsed sooner than expires_in implied. This app runs outside

// the Shopify admin, so it has no ID token to exchange — the refresh token is

// the only way back. Try it once, then give up rather than sending the same

// rejected token again on every later request.

if (response.status === 401) {

const result = await refreshAccessToken(shop);

if (result === 'retry') {

// Transient: the refresh token is untouched, so a later attempt is fine.

return res.status(503).send('Token refresh failed, try again');

}

if (result === 'failed') {

return res.status(502).send('Token refresh failed');

}

if (result !== 'refreshed') {

// Drop the rejected token so the next request doesn't send it again.

delete tokenStore[shop];

return res.status(401).send('Reauthorization required');

}

response = await callAdminApi(tokenStore[shop].access_token);

// Retry once, not in a loop. A freshly refreshed token that's also rejected

// means something is wrong beyond a lapsed credential, so stop and send the

// merchant back through OAuth.

if (response.status === 401) {

delete tokenStore[shop];

return res.status(401).send('Reauthorization required');

}

// Forward Shopify's status. Answering a rate limit or an outage with a 200 and

// an error body in it would tell the client the request succeeded.

res.status(response.status).json(await response.json());

});

// The routes above let a transport failure or timeout propagate. The request never

// reached Shopify, so nothing was consumed and the caller can try again: 503 says

// that, while the stack trace Express would otherwise return says the app is broken.

app.use((err, req, res, next) => {

if (err instanceof ShopifyUnreachable) {

return res.status(503).send('Could not reach Shopify, try again');

}

next(err);

});

app.listen(3000, () => console.log('Server running on http://localhost:3000'));

Anchor to Exchange the code for an offline access tokenExchange the code for an offline access token

Offline access tokens persist across sessions and aren't tied to a specific staff member. Exchange the authorization code for one by sending a POST request to Shopify's token endpoint.

Anchor to Send the token requestSend the token request

New public apps must use expiring offline access tokens. Include expiring=1 in your request. Shopify returns a refresh token alongside your access token. If you're updating an existing public app that still requests non-expiring tokens, see Migrate to expiring offline access tokens.

A successful exchange returns the token and its metadata:

{

"access_token": "f85632530bf277ec9ac6f649fc327f17",

"scope": "read_products,write_orders",

"expires_in": 3600,

"refresh_token": "shprt_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",

"refresh_token_expires_in": 7776000

}

Response fields

Field	Description
`access_token`	The token your app uses to make authenticated API requests. Store it securely.
`scope`	The access scopes that were granted.
`expires_in`	Seconds until the access token expires.
`refresh_token`	Used to get a new access token when the current one expires.
`refresh_token_expires_in`	Seconds until the refresh token expires (90 days).

/node/index.js

100

101

102

103

104

105

106

107

108

109

110

111

112

113

114

115

116

117

118

119

120

121

122

123

124

125

126

127

128

129

130

131

132

133

134

135

136

137

138

139

140

141

142

143

144

145

146

147

148

149

150

151

152

153

154

155

156

157

158

159

160

161

162

163

164

165

166

167

168

169

170

171

172

173

174

175

176

177

178

179

180

181

182

183

184

185

186

187

188

189

190

191

192

193

194

195

196

197

198

199

200

201

202

203

204

205

206

207

208

209

210

211

212

213

214

215

216

217

218

219

220

221

222

223

224

225

226

227

228

229

230

231

232

233

234

235

236

237

238

239

240

241

242

243

244

245

246

247

248

249

250

251

252

253

254

255

256

257

258

259

260

261

262

263

264

265

266

267

268

269

270

271

272

273

274

275

276

277

278

279

280

281

282

283

284

285

286

287

288

289

290

291

292

293

294

295

296

297

import express from 'express';

import crypto from 'crypto';

import cookieParser from 'cookie-parser';

import * as dotenv from 'dotenv';

dotenv.config();

// Falls back to a random secret for local dev. Set COOKIE_SECRET in production

// so signed cookies stay valid across restarts and deployments.

const COOKIE_SECRET = process.env.COOKIE_SECRET || crypto.randomBytes(64).toString('hex');

const app = express();

app.use(cookieParser(COOKIE_SECRET));

const CLIENT_ID = process.env.SHOPIFY_CLIENT_ID;

const CLIENT_SECRET = process.env.SHOPIFY_CLIENT_SECRET;

const REDIRECT_URI = process.env.REDIRECT_URI;

const SCOPES = process.env.SCOPES || 'read_products,write_orders';

// In-memory token store (use a database in production)

const tokenStore = {};

// Send cookies only over HTTPS in production; over plain HTTP on localhost in

// dev. httpOnly + sameSite protect them the rest of the time.

const cookieOptions = {

signed: true,

httpOnly: true,

sameSite: 'lax',

secure: process.env.NODE_ENV === 'production',

};

// A valid expiring-token response includes expires_in (seconds until the access

// token expires). Return null when it's absent or non-positive: treat the token

// as non-expiring and never refresh it. Storing Date.now() instead would make

// the next request refresh a token that has no refresh_token — a permanent 401.

function expiresAtFrom(expiresIn) {

const seconds = Number(expiresIn);

return seconds > 0 ? Date.now() + seconds * 1000 : null;

}

function isValidShopDomain(shop) {

return /^[a-zA-Z0-9][a-zA-Z0-9\-]*\.myshopify\.com$/.test(shop);

}

// Node's fetch has no timeout, so a stalled connection to Shopify would hang a

// request until the client gives up. Give every call a deadline, and tag transport

// failures so callers can tell "Shopify said no" from "we never reached Shopify".

// fetch rejects only on a transport failure or this timeout: every HTTP status,

// including 5xx, resolves and is the caller's to handle.

const SHOPIFY_TIMEOUT_MS = 30_000;

class ShopifyUnreachable extends Error {}

async function shopifyFetch(url, options) {

try {

return await fetch(url, {

...options,

signal: AbortSignal.timeout(SHOPIFY_TIMEOUT_MS),

});

} catch (cause) {

throw new ShopifyUnreachable(`Could not reach ${new URL(url).hostname}`, { cause });

}

app.get('/install', (req, res) => {

const { shop } = req.query;

if (!isValidShopDomain(shop)) {

return res.status(400).send('Invalid shop domain');

}

const nonce = crypto.randomBytes(16).toString('hex');

// Store the nonce in a signed cookie so you can verify it against the callback

res.cookie('oauth_state', nonce, cookieOptions);

const authUrl = `https://${shop}/admin/oauth/authorize?` +

new URLSearchParams({

client_id: CLIENT_ID,

scope: SCOPES,

redirect_uri: REDIRECT_URI,

state: nonce,

});

res.redirect(authUrl);

});

app.get('/callback', async (req, res) => {

const { code, hmac, shop, state } = req.query;

if (!state || state !== req.signedCookies.oauth_state) {

return res.status(403).send('Invalid state parameter');

}

res.clearCookie('oauth_state');

const params = Object.fromEntries(

Object.entries(req.query).filter(([key]) => key !== 'hmac')

);

const message = Object.entries(params).sort().map(([k, v]) => `${k}=${v}`).join('&');

const digest = crypto.createHmac('sha256', CLIENT_SECRET).update(message).digest('hex');

const digestBuf = Buffer.from(digest);

const hmacBuf = Buffer.from(String(hmac));

if (digestBuf.length !== hmacBuf.length || !crypto.timingSafeEqual(digestBuf, hmacBuf)) {

return res.status(403).send('Invalid HMAC');

}

if (!isValidShopDomain(shop)) {

return res.status(400).send('Invalid shop domain');

}

  const tokenResponse = await shopifyFetch(`https://${shop}/admin/oauth/access_token`, {

method: 'POST',

headers: {

'Content-Type': 'application/x-www-form-urlencoded',

Accept: 'application/json',

body: new URLSearchParams({

client_id: CLIENT_ID,

client_secret: CLIENT_SECRET,

code,

expiring: '1',

}),

});

if (!tokenResponse.ok) {

return res.status(403).send('Token exchange failed');

}

  const { access_token, refresh_token, scope, expires_in } = await tokenResponse.json();

const granted = scope.split(',');

// A write_* grant includes its matching read_* scope, so Shopify may return

// only the write scope. Treat a requested read_* as satisfied by its write_*.

const missing = SCOPES.split(',').filter(s =>

!granted.includes(s) &&

!(s.startsWith('read_') && granted.includes(`write_${s.slice(5)}`))

);

if (missing.length > 0) return res.status(403).send(`Missing scopes: ${missing.join(', ')}`);

// Store tokens server-side, keyed by shop (use a database in production).

// Track when the access token expires so requests can refresh it in time.

tokenStore[shop] = {

access_token,

refresh_token,

expires_at: expiresAtFrom(expires_in),

};

// Set a signed session cookie so subsequent requests can identify the shop

res.cookie('shop', shop, cookieOptions);

res.json({ message: 'App installed', shop, scope });

});

// Exchange the stored refresh token for a new access token. The return value

// tells the caller how to react, and matches the refresh error handling used

// across grant types:

// 'refreshed' — got a new access token

// 'reauthorize' — a 401 means the refresh token is terminal (expired, revoked,

// replayed after the one-hour retry window, or the app was

// uninstalled); send the merchant back through OAuth

// 'retry' — a transient failure (network, timeout, 5xx, 429); safe to

// retry later with the same refresh token

// 'failed' — any other non-OK status, such as a malformed request or bad

// client credentials; retrying sends the identical request and

// fails the same way, so surface it instead of hiding it

async function refreshAccessToken(shop) {

const stored = tokenStore[shop];

if (!stored?.refresh_token) return 'reauthorize';

let response;

try {

response = await shopifyFetch(`https://${shop}/admin/oauth/access_token`, {

method: 'POST',

headers: {

'Content-Type': 'application/x-www-form-urlencoded',

Accept: 'application/json',

body: new URLSearchParams({

client_id: CLIENT_ID,

client_secret: CLIENT_SECRET,

grant_type: 'refresh_token',

refresh_token: stored.refresh_token,

}),

});

} catch (error) {

// Only a transport failure or timeout becomes 'retry': the request never

// reached Shopify, so the refresh token is untouched and a later attempt is

// safe. Anything else is a bug in this code — let it surface.

if (!(error instanceof ShopifyUnreachable)) throw error;

return 'retry';

}

// A 401 is terminal: drop the dead token so the merchant reinstalls.

if (response.status === 401) {

delete tokenStore[shop];

return 'reauthorize';

}

// Only a rate limit or a server fault is worth retrying. Treating every other

// non-OK status as transient would retry an unrecoverable refresh forever —

// a 400 for a malformed body, or a 403 for bad client credentials, returns the

// same response no matter how long you wait.

if (response.status === 429 || response.status >= 500) return 'retry';

if (!response.ok) return 'failed';

const { access_token, refresh_token, expires_in } = await response.json();

tokenStore[shop] = {

access_token,

refresh_token,

expires_at: expiresAtFrom(expires_in),

};

return 'refreshed';

}

app.get('/products', async (req, res) => {

const shop = req.signedCookies.shop;

if (!shop) return res.status(401).send('Not authenticated');

let stored = tokenStore[shop];

if (!stored) return res.status(401).send('Not authenticated');

// Expiring access tokens are short-lived. Refresh ~60 seconds before the token

// actually expires so a request never goes out with a token that lapses

// mid-flight.

if (stored.expires_at && Date.now() >= stored.expires_at - 60 * 1000) {

const result = await refreshAccessToken(shop);

if (result === 'reauthorize') {

return res.status(401).send('Reauthorization required');

}

if (result === 'retry') {

return res.status(503).send('Token refresh failed, try again');

}

if (result === 'failed') {

// Not the merchant's problem and not worth retrying: fix the app's request

// or credentials. Don't fall through — `stored` still holds the token that

// is about to expire.

return res.status(502).send('Token refresh failed');

}

stored = tokenStore[shop];

}

const callAdminApi = (accessToken) =>

shopifyFetch(`https://${shop}/admin/api/2026-04/graphql.json`, {

method: 'POST',

headers: {

'Content-Type': 'application/json',

'X-Shopify-Access-Token': accessToken,

body: JSON.stringify({ query: '{ products(first: 5) { edges { node { id handle } } } }' }),

});

let response = await callAdminApi(stored.access_token);

// Shopify rejected the access token: it was revoked, the app's access scopes

// changed, or it lapsed sooner than expires_in implied. This app runs outside

// the Shopify admin, so it has no ID token to exchange — the refresh token is

// the only way back. Try it once, then give up rather than sending the same

// rejected token again on every later request.

if (response.status === 401) {

const result = await refreshAccessToken(shop);

if (result === 'retry') {

// Transient: the refresh token is untouched, so a later attempt is fine.

return res.status(503).send('Token refresh failed, try again');

}

if (result === 'failed') {

return res.status(502).send('Token refresh failed');

}

if (result !== 'refreshed') {

// Drop the rejected token so the next request doesn't send it again.

delete tokenStore[shop];

return res.status(401).send('Reauthorization required');

}

response = await callAdminApi(tokenStore[shop].access_token);

// Retry once, not in a loop. A freshly refreshed token that's also rejected

// means something is wrong beyond a lapsed credential, so stop and send the

// merchant back through OAuth.

if (response.status === 401) {

delete tokenStore[shop];

return res.status(401).send('Reauthorization required');

}

// Forward Shopify's status. Answering a rate limit or an outage with a 200 and

// an error body in it would tell the client the request succeeded.

res.status(response.status).json(await response.json());

});

// The routes above let a transport failure or timeout propagate. The request never

// reached Shopify, so nothing was consumed and the caller can try again: 503 says

// that, while the stack trace Express would otherwise return says the app is broken.

app.use((err, req, res, next) => {

if (err instanceof ShopifyUnreachable) {

return res.status(503).send('Could not reach Shopify, try again');

}

next(err);

});

app.listen(3000, () => console.log('Server running on http://localhost:3000'));

Anchor to Confirm the granted scopesConfirm the granted scopes

Check that scope in the response includes all the scopes your app requires. Merchants can modify requested scopes during authorization, so always verify before storing the token. A write_* scope includes its matching read_* scope, so when you check the granted scope list, look for the write scope you requested rather than a separate read scope.

To request additional scopes later, redirect the merchant to the authorization URL again with the updated scope list. Shopify prompts them to approve the added permissions. Apps built with Shopify CLI update scopes through managed installation instead. See Authentication for apps built with Shopify CLI.

/node/index.js

100

101

102

103

104

105

106

107

108

109

110

111

112

113

114

115

116

117

118

119

120

121

122

123

124

125

126

127

128

129

130

131

132

133

134

135

136

137

138

139

140

141

142

143

144

145

146

147

148

149

150

151

152

153

154

155

156

157

158

159

160

161

162

163

164

165

166

167

168

169

170

171

172

173

174

175

176

177

178

179

180

181

182

183

184

185

186

187

188

189

190

191

192

193

194

195

196

197

198

199

200

201

202

203

204

205

206

207

208

209

210

211

212

213

214

215

216

217

218

219

220

221

222

223

224

225

226

227

228

229

230

231

232

233

234

235

236

237

238

239

240

241

242

243

244

245

246

247

248

249

250

251

252

253

254

255

256

257

258

259

260

261

262

263

264

265

266

267

268

269

270

271

272

273

274

275

276

277

278

279

280

281

282

283

284

285

286

287

288

289

290

291

292

293

294

295

296

297

import express from 'express';

import crypto from 'crypto';

import cookieParser from 'cookie-parser';

import * as dotenv from 'dotenv';

dotenv.config();

// Falls back to a random secret for local dev. Set COOKIE_SECRET in production

// so signed cookies stay valid across restarts and deployments.

const COOKIE_SECRET = process.env.COOKIE_SECRET || crypto.randomBytes(64).toString('hex');

const app = express();

app.use(cookieParser(COOKIE_SECRET));

const CLIENT_ID = process.env.SHOPIFY_CLIENT_ID;

const CLIENT_SECRET = process.env.SHOPIFY_CLIENT_SECRET;

const REDIRECT_URI = process.env.REDIRECT_URI;

const SCOPES = process.env.SCOPES || 'read_products,write_orders';

// In-memory token store (use a database in production)

const tokenStore = {};

// Send cookies only over HTTPS in production; over plain HTTP on localhost in

// dev. httpOnly + sameSite protect them the rest of the time.

const cookieOptions = {

signed: true,

httpOnly: true,

sameSite: 'lax',

secure: process.env.NODE_ENV === 'production',

};

// A valid expiring-token response includes expires_in (seconds until the access

// token expires). Return null when it's absent or non-positive: treat the token

// as non-expiring and never refresh it. Storing Date.now() instead would make

// the next request refresh a token that has no refresh_token — a permanent 401.

function expiresAtFrom(expiresIn) {

const seconds = Number(expiresIn);

return seconds > 0 ? Date.now() + seconds * 1000 : null;

}

function isValidShopDomain(shop) {

return /^[a-zA-Z0-9][a-zA-Z0-9\-]*\.myshopify\.com$/.test(shop);

}

// Node's fetch has no timeout, so a stalled connection to Shopify would hang a

// request until the client gives up. Give every call a deadline, and tag transport

// failures so callers can tell "Shopify said no" from "we never reached Shopify".

// fetch rejects only on a transport failure or this timeout: every HTTP status,

// including 5xx, resolves and is the caller's to handle.

const SHOPIFY_TIMEOUT_MS = 30_000;

class ShopifyUnreachable extends Error {}

async function shopifyFetch(url, options) {

try {

return await fetch(url, {

...options,

signal: AbortSignal.timeout(SHOPIFY_TIMEOUT_MS),

});

} catch (cause) {

throw new ShopifyUnreachable(`Could not reach ${new URL(url).hostname}`, { cause });

}

app.get('/install', (req, res) => {

const { shop } = req.query;

if (!isValidShopDomain(shop)) {

return res.status(400).send('Invalid shop domain');

}

const nonce = crypto.randomBytes(16).toString('hex');

// Store the nonce in a signed cookie so you can verify it against the callback

res.cookie('oauth_state', nonce, cookieOptions);

const authUrl = `https://${shop}/admin/oauth/authorize?` +

new URLSearchParams({

client_id: CLIENT_ID,

scope: SCOPES,

redirect_uri: REDIRECT_URI,

state: nonce,

});

res.redirect(authUrl);

});

app.get('/callback', async (req, res) => {

const { code, hmac, shop, state } = req.query;

if (!state || state !== req.signedCookies.oauth_state) {

return res.status(403).send('Invalid state parameter');

}

res.clearCookie('oauth_state');

const params = Object.fromEntries(

Object.entries(req.query).filter(([key]) => key !== 'hmac')

);

const message = Object.entries(params).sort().map(([k, v]) => `${k}=${v}`).join('&');

const digest = crypto.createHmac('sha256', CLIENT_SECRET).update(message).digest('hex');

const digestBuf = Buffer.from(digest);

const hmacBuf = Buffer.from(String(hmac));

if (digestBuf.length !== hmacBuf.length || !crypto.timingSafeEqual(digestBuf, hmacBuf)) {

return res.status(403).send('Invalid HMAC');

}

if (!isValidShopDomain(shop)) {

return res.status(400).send('Invalid shop domain');

}

const tokenResponse = await shopifyFetch(`https://${shop}/admin/oauth/access_token`, {

method: 'POST',

headers: {

'Content-Type': 'application/x-www-form-urlencoded',

Accept: 'application/json',

body: new URLSearchParams({

client_id: CLIENT_ID,

client_secret: CLIENT_SECRET,

code,

expiring: '1',

}),

});

if (!tokenResponse.ok) {

return res.status(403).send('Token exchange failed');

}

const { access_token, refresh_token, scope, expires_in } = await tokenResponse.json();

const granted = scope.split(',');

// A write_* grant includes its matching read_* scope, so Shopify may return

// only the write scope. Treat a requested read_* as satisfied by its write_*.

const missing = SCOPES.split(',').filter(s =>

!granted.includes(s) &&

!(s.startsWith('read_') && granted.includes(`write_${s.slice(5)}`))

);

  if (missing.length > 0) return res.status(403).send(`Missing scopes: ${missing.join(', ')}`);

// Store tokens server-side, keyed by shop (use a database in production).

// Track when the access token expires so requests can refresh it in time.

tokenStore[shop] = {

access_token,

refresh_token,

expires_at: expiresAtFrom(expires_in),

};

// Set a signed session cookie so subsequent requests can identify the shop

res.cookie('shop', shop, cookieOptions);

res.json({ message: 'App installed', shop, scope });

});

// Exchange the stored refresh token for a new access token. The return value

// tells the caller how to react, and matches the refresh error handling used

// across grant types:

// 'refreshed' — got a new access token

// 'reauthorize' — a 401 means the refresh token is terminal (expired, revoked,

// replayed after the one-hour retry window, or the app was

// uninstalled); send the merchant back through OAuth

// 'retry' — a transient failure (network, timeout, 5xx, 429); safe to

// retry later with the same refresh token

// 'failed' — any other non-OK status, such as a malformed request or bad

// client credentials; retrying sends the identical request and

// fails the same way, so surface it instead of hiding it

async function refreshAccessToken(shop) {

const stored = tokenStore[shop];

if (!stored?.refresh_token) return 'reauthorize';

let response;

try {

response = await shopifyFetch(`https://${shop}/admin/oauth/access_token`, {

method: 'POST',

headers: {

'Content-Type': 'application/x-www-form-urlencoded',

Accept: 'application/json',

body: new URLSearchParams({

client_id: CLIENT_ID,

client_secret: CLIENT_SECRET,

grant_type: 'refresh_token',

refresh_token: stored.refresh_token,

}),

});

} catch (error) {

// Only a transport failure or timeout becomes 'retry': the request never

// reached Shopify, so the refresh token is untouched and a later attempt is

// safe. Anything else is a bug in this code — let it surface.

if (!(error instanceof ShopifyUnreachable)) throw error;

return 'retry';

}

// A 401 is terminal: drop the dead token so the merchant reinstalls.

if (response.status === 401) {

delete tokenStore[shop];

return 'reauthorize';

}

// Only a rate limit or a server fault is worth retrying. Treating every other

// non-OK status as transient would retry an unrecoverable refresh forever —

// a 400 for a malformed body, or a 403 for bad client credentials, returns the

// same response no matter how long you wait.

if (response.status === 429 || response.status >= 500) return 'retry';

if (!response.ok) return 'failed';

const { access_token, refresh_token, expires_in } = await response.json();

tokenStore[shop] = {

access_token,

refresh_token,

expires_at: expiresAtFrom(expires_in),

};

return 'refreshed';

}

app.get('/products', async (req, res) => {

const shop = req.signedCookies.shop;

if (!shop) return res.status(401).send('Not authenticated');

let stored = tokenStore[shop];

if (!stored) return res.status(401).send('Not authenticated');

// Expiring access tokens are short-lived. Refresh ~60 seconds before the token

// actually expires so a request never goes out with a token that lapses

// mid-flight.

if (stored.expires_at && Date.now() >= stored.expires_at - 60 * 1000) {

const result = await refreshAccessToken(shop);

if (result === 'reauthorize') {

return res.status(401).send('Reauthorization required');

}

if (result === 'retry') {

return res.status(503).send('Token refresh failed, try again');

}

if (result === 'failed') {

// Not the merchant's problem and not worth retrying: fix the app's request

// or credentials. Don't fall through — `stored` still holds the token that

// is about to expire.

return res.status(502).send('Token refresh failed');

}

stored = tokenStore[shop];

}

const callAdminApi = (accessToken) =>

shopifyFetch(`https://${shop}/admin/api/2026-04/graphql.json`, {

method: 'POST',

headers: {

'Content-Type': 'application/json',

'X-Shopify-Access-Token': accessToken,

body: JSON.stringify({ query: '{ products(first: 5) { edges { node { id handle } } } }' }),

});

let response = await callAdminApi(stored.access_token);

// Shopify rejected the access token: it was revoked, the app's access scopes

// changed, or it lapsed sooner than expires_in implied. This app runs outside

// the Shopify admin, so it has no ID token to exchange — the refresh token is

// the only way back. Try it once, then give up rather than sending the same

// rejected token again on every later request.

if (response.status === 401) {

const result = await refreshAccessToken(shop);

if (result === 'retry') {

// Transient: the refresh token is untouched, so a later attempt is fine.

return res.status(503).send('Token refresh failed, try again');

}

if (result === 'failed') {

return res.status(502).send('Token refresh failed');

}

if (result !== 'refreshed') {

// Drop the rejected token so the next request doesn't send it again.

delete tokenStore[shop];

return res.status(401).send('Reauthorization required');

}

response = await callAdminApi(tokenStore[shop].access_token);

// Retry once, not in a loop. A freshly refreshed token that's also rejected

// means something is wrong beyond a lapsed credential, so stop and send the

// merchant back through OAuth.

if (response.status === 401) {

delete tokenStore[shop];

return res.status(401).send('Reauthorization required');

}

// Forward Shopify's status. Answering a rate limit or an outage with a 200 and

// an error body in it would tell the client the request succeeded.

res.status(response.status).json(await response.json());

});

// The routes above let a transport failure or timeout propagate. The request never

// reached Shopify, so nothing was consumed and the caller can try again: 503 says

// that, while the stack trace Express would otherwise return says the app is broken.

app.use((err, req, res, next) => {

if (err instanceof ShopifyUnreachable) {

return res.status(503).send('Could not reach Shopify, try again');

}

next(err);

});

app.listen(3000, () => console.log('Server running on http://localhost:3000'));

Anchor to Store the tokensStore the tokens

Store the access_token and refresh_token securely on your backend, along with expires_in and refresh_token_expires_in so you know when each token expires.

/node/index.js

100

101

102

103

104

105

106

107

108

109

110

111

112

113

114

115

116

117

118

119

120

121

122

123

124

125

126

127

128

129

130

131

132

133

134

135

136

137

138

139

140

141

142

143

144

145

146

147

148

149

150

151

152

153

154

155

156

157

158

159

160

161

162

163

164

165

166

167

168

169

170

171

172

173

174

175

176

177

178

179

180

181

182

183

184

185

186

187

188

189

190

191

192

193

194

195

196

197

198

199

200

201

202

203

204

205

206

207

208

209

210

211

212

213

214

215

216

217

218

219

220

221

222

223

224

225

226

227

228

229

230

231

232

233

234

235

236

237

238

239

240

241

242

243

244

245

246

247

248

249

250

251

252

253

254

255

256

257

258

259

260

261

262

263

264

265

266

267

268

269

270

271

272

273

274

275

276

277

278

279

280

281

282

283

284

285

286

287

288

289

290

291

292

293

294

295

296

297

import express from 'express';

import crypto from 'crypto';

import cookieParser from 'cookie-parser';

import * as dotenv from 'dotenv';

dotenv.config();

// Falls back to a random secret for local dev. Set COOKIE_SECRET in production

// so signed cookies stay valid across restarts and deployments.

const COOKIE_SECRET = process.env.COOKIE_SECRET || crypto.randomBytes(64).toString('hex');

const app = express();

app.use(cookieParser(COOKIE_SECRET));

const CLIENT_ID = process.env.SHOPIFY_CLIENT_ID;

const CLIENT_SECRET = process.env.SHOPIFY_CLIENT_SECRET;

const REDIRECT_URI = process.env.REDIRECT_URI;

const SCOPES = process.env.SCOPES || 'read_products,write_orders';

// In-memory token store (use a database in production)

const tokenStore = {};

// Send cookies only over HTTPS in production; over plain HTTP on localhost in

// dev. httpOnly + sameSite protect them the rest of the time.

const cookieOptions = {

signed: true,

httpOnly: true,

sameSite: 'lax',

secure: process.env.NODE_ENV === 'production',

};

// A valid expiring-token response includes expires_in (seconds until the access

// token expires). Return null when it's absent or non-positive: treat the token

// as non-expiring and never refresh it. Storing Date.now() instead would make

// the next request refresh a token that has no refresh_token — a permanent 401.

function expiresAtFrom(expiresIn) {

const seconds = Number(expiresIn);

return seconds > 0 ? Date.now() + seconds * 1000 : null;

}

function isValidShopDomain(shop) {

return /^[a-zA-Z0-9][a-zA-Z0-9\-]*\.myshopify\.com$/.test(shop);

}

// Node's fetch has no timeout, so a stalled connection to Shopify would hang a

// request until the client gives up. Give every call a deadline, and tag transport

// failures so callers can tell "Shopify said no" from "we never reached Shopify".

// fetch rejects only on a transport failure or this timeout: every HTTP status,

// including 5xx, resolves and is the caller's to handle.

const SHOPIFY_TIMEOUT_MS = 30_000;

class ShopifyUnreachable extends Error {}

async function shopifyFetch(url, options) {

try {

return await fetch(url, {

...options,

signal: AbortSignal.timeout(SHOPIFY_TIMEOUT_MS),

});

} catch (cause) {

throw new ShopifyUnreachable(`Could not reach ${new URL(url).hostname}`, { cause });

}

app.get('/install', (req, res) => {

const { shop } = req.query;

if (!isValidShopDomain(shop)) {

return res.status(400).send('Invalid shop domain');

}

const nonce = crypto.randomBytes(16).toString('hex');

// Store the nonce in a signed cookie so you can verify it against the callback

res.cookie('oauth_state', nonce, cookieOptions);

const authUrl = `https://${shop}/admin/oauth/authorize?` +

new URLSearchParams({

client_id: CLIENT_ID,

scope: SCOPES,

redirect_uri: REDIRECT_URI,

state: nonce,

});

res.redirect(authUrl);

});

app.get('/callback', async (req, res) => {

const { code, hmac, shop, state } = req.query;

if (!state || state !== req.signedCookies.oauth_state) {

return res.status(403).send('Invalid state parameter');

}

res.clearCookie('oauth_state');

const params = Object.fromEntries(

Object.entries(req.query).filter(([key]) => key !== 'hmac')

);

const message = Object.entries(params).sort().map(([k, v]) => `${k}=${v}`).join('&');

const digest = crypto.createHmac('sha256', CLIENT_SECRET).update(message).digest('hex');

const digestBuf = Buffer.from(digest);

const hmacBuf = Buffer.from(String(hmac));

if (digestBuf.length !== hmacBuf.length || !crypto.timingSafeEqual(digestBuf, hmacBuf)) {

return res.status(403).send('Invalid HMAC');

}

if (!isValidShopDomain(shop)) {

return res.status(400).send('Invalid shop domain');

}

const tokenResponse = await shopifyFetch(`https://${shop}/admin/oauth/access_token`, {

method: 'POST',

headers: {

'Content-Type': 'application/x-www-form-urlencoded',

Accept: 'application/json',

body: new URLSearchParams({

client_id: CLIENT_ID,

client_secret: CLIENT_SECRET,

code,

expiring: '1',

}),

});

if (!tokenResponse.ok) {

return res.status(403).send('Token exchange failed');

}

const { access_token, refresh_token, scope, expires_in } = await tokenResponse.json();

const granted = scope.split(',');

// A write_* grant includes its matching read_* scope, so Shopify may return

// only the write scope. Treat a requested read_* as satisfied by its write_*.

const missing = SCOPES.split(',').filter(s =>

!granted.includes(s) &&

!(s.startsWith('read_') && granted.includes(`write_${s.slice(5)}`))

);

if (missing.length > 0) return res.status(403).send(`Missing scopes: ${missing.join(', ')}`);

// Store tokens server-side, keyed by shop (use a database in production).

// Track when the access token expires so requests can refresh it in time.

tokenStore[shop] = {

access_token,

refresh_token,

expires_at: expiresAtFrom(expires_in),

};

// Set a signed session cookie so subsequent requests can identify the shop

res.cookie('shop', shop, cookieOptions);

res.json({ message: 'App installed', shop, scope });

});

// Exchange the stored refresh token for a new access token. The return value

// tells the caller how to react, and matches the refresh error handling used

// across grant types:

// 'refreshed' — got a new access token

// 'reauthorize' — a 401 means the refresh token is terminal (expired, revoked,

// replayed after the one-hour retry window, or the app was

// uninstalled); send the merchant back through OAuth

// 'retry' — a transient failure (network, timeout, 5xx, 429); safe to

// retry later with the same refresh token

// 'failed' — any other non-OK status, such as a malformed request or bad

// client credentials; retrying sends the identical request and

// fails the same way, so surface it instead of hiding it

async function refreshAccessToken(shop) {

const stored = tokenStore[shop];

if (!stored?.refresh_token) return 'reauthorize';

let response;

try {

response = await shopifyFetch(`https://${shop}/admin/oauth/access_token`, {

method: 'POST',

headers: {

'Content-Type': 'application/x-www-form-urlencoded',

Accept: 'application/json',

body: new URLSearchParams({

client_id: CLIENT_ID,

client_secret: CLIENT_SECRET,

grant_type: 'refresh_token',

refresh_token: stored.refresh_token,

}),

});

} catch (error) {

// Only a transport failure or timeout becomes 'retry': the request never

// reached Shopify, so the refresh token is untouched and a later attempt is

// safe. Anything else is a bug in this code — let it surface.

if (!(error instanceof ShopifyUnreachable)) throw error;

return 'retry';

}

// A 401 is terminal: drop the dead token so the merchant reinstalls.

if (response.status === 401) {

delete tokenStore[shop];

return 'reauthorize';

}

// Only a rate limit or a server fault is worth retrying. Treating every other

// non-OK status as transient would retry an unrecoverable refresh forever —

// a 400 for a malformed body, or a 403 for bad client credentials, returns the

// same response no matter how long you wait.

if (response.status === 429 || response.status >= 500) return 'retry';

if (!response.ok) return 'failed';

const { access_token, refresh_token, expires_in } = await response.json();

tokenStore[shop] = {

access_token,

refresh_token,

expires_at: expiresAtFrom(expires_in),

};

return 'refreshed';

}

app.get('/products', async (req, res) => {

const shop = req.signedCookies.shop;

if (!shop) return res.status(401).send('Not authenticated');

let stored = tokenStore[shop];

if (!stored) return res.status(401).send('Not authenticated');

// Expiring access tokens are short-lived. Refresh ~60 seconds before the token

// actually expires so a request never goes out with a token that lapses

// mid-flight.

if (stored.expires_at && Date.now() >= stored.expires_at - 60 * 1000) {

const result = await refreshAccessToken(shop);

if (result === 'reauthorize') {

return res.status(401).send('Reauthorization required');

}

if (result === 'retry') {

return res.status(503).send('Token refresh failed, try again');

}

if (result === 'failed') {

// Not the merchant's problem and not worth retrying: fix the app's request

// or credentials. Don't fall through — `stored` still holds the token that

// is about to expire.

return res.status(502).send('Token refresh failed');

}

stored = tokenStore[shop];

}

const callAdminApi = (accessToken) =>

shopifyFetch(`https://${shop}/admin/api/2026-04/graphql.json`, {

method: 'POST',

headers: {

'Content-Type': 'application/json',

'X-Shopify-Access-Token': accessToken,

body: JSON.stringify({ query: '{ products(first: 5) { edges { node { id handle } } } }' }),

});

let response = await callAdminApi(stored.access_token);

// Shopify rejected the access token: it was revoked, the app's access scopes

// changed, or it lapsed sooner than expires_in implied. This app runs outside

// the Shopify admin, so it has no ID token to exchange — the refresh token is

// the only way back. Try it once, then give up rather than sending the same

// rejected token again on every later request.

if (response.status === 401) {

const result = await refreshAccessToken(shop);

if (result === 'retry') {

// Transient: the refresh token is untouched, so a later attempt is fine.

return res.status(503).send('Token refresh failed, try again');

}

if (result === 'failed') {

return res.status(502).send('Token refresh failed');

}

if (result !== 'refreshed') {

// Drop the rejected token so the next request doesn't send it again.

delete tokenStore[shop];

return res.status(401).send('Reauthorization required');

}

response = await callAdminApi(tokenStore[shop].access_token);

// Retry once, not in a loop. A freshly refreshed token that's also rejected

// means something is wrong beyond a lapsed credential, so stop and send the

// merchant back through OAuth.

if (response.status === 401) {

delete tokenStore[shop];

return res.status(401).send('Reauthorization required');

}

// Forward Shopify's status. Answering a rate limit or an outage with a 200 and

// an error body in it would tell the client the request succeeded.

res.status(response.status).json(await response.json());

});

// The routes above let a transport failure or timeout propagate. The request never

// reached Shopify, so nothing was consumed and the caller can try again: 503 says

// that, while the stack trace Express would otherwise return says the app is broken.

app.use((err, req, res, next) => {

if (err instanceof ShopifyUnreachable) {

return res.status(503).send('Could not reach Shopify, try again');

}

next(err);

});

app.listen(3000, () => console.log('Server running on http://localhost:3000'));

Anchor to (Optional) Request an online access token(Optional) Request an online access token

Online access tokens are scoped to the staff member who authorized them, and they expire with that user's session. Request one when your app needs to respect an individual user's permission level or attribute actions to a specific user. Skip this step if an offline token is all your app needs.

A single authorization request returns one token type, so this step changes the flow you just built rather than adding to it. Your app can hold both, but each one needs its own record: key the offline token by shop, and each online token by shop and staff member. An online access token has no refresh token, so writing one into the offline token's record ends your app's background refresh. The samples on this page keep a single record per shop, so add a second store before you run this flow.

Anchor to Add the per-user parameter to the authorization URLAdd the per-user parameter to the authorization URL

Append &grant_options[]=per-user to the authorization URL you built in Redirect to Shopify's authorization page, then run the flow again. The code exchange returns an online access token instead of an offline one, and the response adds associated_user and associated_user_scope.

https://{shop}/admin/oauth/authorize?client_id={client_id}&scope={scopes}&redirect_uri={redirect_uri}&state={nonce}&grant_options[]=per-user

For what those fields contain, how long the token lasts, what a user logging out revokes, and why a valid token can still return 403, see Online access tokens.

Anchor to Make authenticated API requestsMake authenticated API requests

Include the access token in the X-Shopify-Access-Token header on all GraphQL Admin API requests.

Anchor to Add the access token headerAdd the access token header

Include the access token in every request. When it nears expiry, use the stored refresh_token to get a new one rather than sending the merchant back through authorization. See Refresh the access token.

/node/index.js

100

101

102

103

104

105

106

107

108

109

110

111

112

113

114

115

116

117

118

119

120

121

122

123

124

125

126

127

128

129

130

131

132

133

134

135

136

137

138

139

140

141

142

143

144

145

146

147

148

149

150

151

152

153

154

155

156

157

158

159

160

161

162

163

164

165

166

167

168

169

170

171

172

173

174

175

176

177

178

179

180

181

182

183

184

185

186

187

188

189

190

191

192

193

194

195

196

197

198

199

200

201

202

203

204

205

206

207

208

209

210

211

212

213

214

215

216

217

218

219

220

221

222

223

224

225

226

227

228

229

230

231

232

233

234

235

236

237

238

239

240

241

242

243

244

245

246

247

248

249

250

251

252

253

254

255

256

257

258

259

260

261

262

263

264

265

266

267

268

269

270

271

272

273

274

275

276

277

278

279

280

281

282

283

284

285

286

287

288

289

290

291

292

293

294

295

296

297

import express from 'express';

import crypto from 'crypto';

import cookieParser from 'cookie-parser';

import * as dotenv from 'dotenv';

dotenv.config();

// Falls back to a random secret for local dev. Set COOKIE_SECRET in production

// so signed cookies stay valid across restarts and deployments.

const COOKIE_SECRET = process.env.COOKIE_SECRET || crypto.randomBytes(64).toString('hex');

const app = express();

app.use(cookieParser(COOKIE_SECRET));

const CLIENT_ID = process.env.SHOPIFY_CLIENT_ID;

const CLIENT_SECRET = process.env.SHOPIFY_CLIENT_SECRET;

const REDIRECT_URI = process.env.REDIRECT_URI;

const SCOPES = process.env.SCOPES || 'read_products,write_orders';

// In-memory token store (use a database in production)

const tokenStore = {};

// Send cookies only over HTTPS in production; over plain HTTP on localhost in

// dev. httpOnly + sameSite protect them the rest of the time.

const cookieOptions = {

signed: true,

httpOnly: true,

sameSite: 'lax',

secure: process.env.NODE_ENV === 'production',

};

// A valid expiring-token response includes expires_in (seconds until the access

// token expires). Return null when it's absent or non-positive: treat the token

// as non-expiring and never refresh it. Storing Date.now() instead would make

// the next request refresh a token that has no refresh_token — a permanent 401.

function expiresAtFrom(expiresIn) {

const seconds = Number(expiresIn);

return seconds > 0 ? Date.now() + seconds * 1000 : null;

}

function isValidShopDomain(shop) {

return /^[a-zA-Z0-9][a-zA-Z0-9\-]*\.myshopify\.com$/.test(shop);

}

// Node's fetch has no timeout, so a stalled connection to Shopify would hang a

// request until the client gives up. Give every call a deadline, and tag transport

// failures so callers can tell "Shopify said no" from "we never reached Shopify".

// fetch rejects only on a transport failure or this timeout: every HTTP status,

// including 5xx, resolves and is the caller's to handle.

const SHOPIFY_TIMEOUT_MS = 30_000;

class ShopifyUnreachable extends Error {}

async function shopifyFetch(url, options) {

try {

return await fetch(url, {

...options,

signal: AbortSignal.timeout(SHOPIFY_TIMEOUT_MS),

});

} catch (cause) {

throw new ShopifyUnreachable(`Could not reach ${new URL(url).hostname}`, { cause });

}

app.get('/install', (req, res) => {

const { shop } = req.query;

if (!isValidShopDomain(shop)) {

return res.status(400).send('Invalid shop domain');

}

const nonce = crypto.randomBytes(16).toString('hex');

// Store the nonce in a signed cookie so you can verify it against the callback

res.cookie('oauth_state', nonce, cookieOptions);

const authUrl = `https://${shop}/admin/oauth/authorize?` +

new URLSearchParams({

client_id: CLIENT_ID,

scope: SCOPES,

redirect_uri: REDIRECT_URI,

state: nonce,

});

res.redirect(authUrl);

});

app.get('/callback', async (req, res) => {

const { code, hmac, shop, state } = req.query;

if (!state || state !== req.signedCookies.oauth_state) {

return res.status(403).send('Invalid state parameter');

}

res.clearCookie('oauth_state');

const params = Object.fromEntries(

Object.entries(req.query).filter(([key]) => key !== 'hmac')

);

const message = Object.entries(params).sort().map(([k, v]) => `${k}=${v}`).join('&');

const digest = crypto.createHmac('sha256', CLIENT_SECRET).update(message).digest('hex');

const digestBuf = Buffer.from(digest);

const hmacBuf = Buffer.from(String(hmac));

if (digestBuf.length !== hmacBuf.length || !crypto.timingSafeEqual(digestBuf, hmacBuf)) {

return res.status(403).send('Invalid HMAC');

}

if (!isValidShopDomain(shop)) {

return res.status(400).send('Invalid shop domain');

}

const tokenResponse = await shopifyFetch(`https://${shop}/admin/oauth/access_token`, {

method: 'POST',

headers: {

'Content-Type': 'application/x-www-form-urlencoded',

Accept: 'application/json',

body: new URLSearchParams({

client_id: CLIENT_ID,

client_secret: CLIENT_SECRET,

code,

expiring: '1',

}),

});

if (!tokenResponse.ok) {

return res.status(403).send('Token exchange failed');

}

const { access_token, refresh_token, scope, expires_in } = await tokenResponse.json();

const granted = scope.split(',');

// A write_* grant includes its matching read_* scope, so Shopify may return

// only the write scope. Treat a requested read_* as satisfied by its write_*.

const missing = SCOPES.split(',').filter(s =>

!granted.includes(s) &&

!(s.startsWith('read_') && granted.includes(`write_${s.slice(5)}`))

);

if (missing.length > 0) return res.status(403).send(`Missing scopes: ${missing.join(', ')}`);

// Store tokens server-side, keyed by shop (use a database in production).

// Track when the access token expires so requests can refresh it in time.

tokenStore[shop] = {

access_token,

refresh_token,

expires_at: expiresAtFrom(expires_in),

};

// Set a signed session cookie so subsequent requests can identify the shop

res.cookie('shop', shop, cookieOptions);

res.json({ message: 'App installed', shop, scope });

});

// Exchange the stored refresh token for a new access token. The return value

// tells the caller how to react, and matches the refresh error handling used

// across grant types:

// 'refreshed' — got a new access token

// 'reauthorize' — a 401 means the refresh token is terminal (expired, revoked,

// replayed after the one-hour retry window, or the app was

// uninstalled); send the merchant back through OAuth

// 'retry' — a transient failure (network, timeout, 5xx, 429); safe to

// retry later with the same refresh token

// 'failed' — any other non-OK status, such as a malformed request or bad

// client credentials; retrying sends the identical request and

// fails the same way, so surface it instead of hiding it

async function refreshAccessToken(shop) {

const stored = tokenStore[shop];

if (!stored?.refresh_token) return 'reauthorize';

let response;

try {

response = await shopifyFetch(`https://${shop}/admin/oauth/access_token`, {

method: 'POST',

headers: {

'Content-Type': 'application/x-www-form-urlencoded',

Accept: 'application/json',

body: new URLSearchParams({

client_id: CLIENT_ID,

client_secret: CLIENT_SECRET,

grant_type: 'refresh_token',

refresh_token: stored.refresh_token,

}),

});

} catch (error) {

// Only a transport failure or timeout becomes 'retry': the request never

// reached Shopify, so the refresh token is untouched and a later attempt is

// safe. Anything else is a bug in this code — let it surface.

if (!(error instanceof ShopifyUnreachable)) throw error;

return 'retry';

}

// A 401 is terminal: drop the dead token so the merchant reinstalls.

if (response.status === 401) {

delete tokenStore[shop];

return 'reauthorize';

}

// Only a rate limit or a server fault is worth retrying. Treating every other

// non-OK status as transient would retry an unrecoverable refresh forever —

// a 400 for a malformed body, or a 403 for bad client credentials, returns the

// same response no matter how long you wait.

if (response.status === 429 || response.status >= 500) return 'retry';

if (!response.ok) return 'failed';

const { access_token, refresh_token, expires_in } = await response.json();

tokenStore[shop] = {

access_token,

refresh_token,

expires_at: expiresAtFrom(expires_in),

};

return 'refreshed';

}

app.get('/products', async (req, res) => {

const shop = req.signedCookies.shop;

if (!shop) return res.status(401).send('Not authenticated');

let stored = tokenStore[shop];

if (!stored) return res.status(401).send('Not authenticated');

// Expiring access tokens are short-lived. Refresh ~60 seconds before the token

// actually expires so a request never goes out with a token that lapses

// mid-flight.

if (stored.expires_at && Date.now() >= stored.expires_at - 60 * 1000) {

const result = await refreshAccessToken(shop);

if (result === 'reauthorize') {

return res.status(401).send('Reauthorization required');

}

if (result === 'retry') {

return res.status(503).send('Token refresh failed, try again');

}

if (result === 'failed') {

// Not the merchant's problem and not worth retrying: fix the app's request

// or credentials. Don't fall through — `stored` still holds the token that

// is about to expire.

return res.status(502).send('Token refresh failed');

}

stored = tokenStore[shop];

}

const callAdminApi = (accessToken) =>

shopifyFetch(`https://${shop}/admin/api/2026-04/graphql.json`, {

method: 'POST',

headers: {

'Content-Type': 'application/json',

'X-Shopify-Access-Token': accessToken,

      body: JSON.stringify({ query: '{ products(first: 5) { edges { node { id handle } } } }' }),

});

let response = await callAdminApi(stored.access_token);

// Shopify rejected the access token: it was revoked, the app's access scopes

// changed, or it lapsed sooner than expires_in implied. This app runs outside

  // the Shopify admin, so it has no ID token to exchange — the refresh token is

// the only way back. Try it once, then give up rather than sending the same

// rejected token again on every later request.

if (response.status === 401) {

const result = await refreshAccessToken(shop);

if (result === 'retry') {

// Transient: the refresh token is untouched, so a later attempt is fine.

return res.status(503).send('Token refresh failed, try again');

}

if (result === 'failed') {

return res.status(502).send('Token refresh failed');

}

if (result !== 'refreshed') {

// Drop the rejected token so the next request doesn't send it again.

delete tokenStore[shop];

return res.status(401).send('Reauthorization required');

}

response = await callAdminApi(tokenStore[shop].access_token);

// Retry once, not in a loop. A freshly refreshed token that's also rejected

// means something is wrong beyond a lapsed credential, so stop and send the

// merchant back through OAuth.

if (response.status === 401) {

delete tokenStore[shop];

return res.status(401).send('Reauthorization required');

}

// Forward Shopify's status. Answering a rate limit or an outage with a 200 and

// an error body in it would tell the client the request succeeded.

res.status(response.status).json(await response.json());

});

// The routes above let a transport failure or timeout propagate. The request never

// reached Shopify, so nothing was consumed and the caller can try again: 503 says

// that, while the stack trace Express would otherwise return says the app is broken.

app.use((err, req, res, next) => {

if (err instanceof ShopifyUnreachable) {

return res.status(503).send('Could not reach Shopify, try again');

}

next(err);

});

app.listen(3000, () => console.log('Server running on http://localhost:3000'));

Anchor to Refresh the access tokenRefresh the access token

Expiring offline access tokens come with a refresh_token. Before the access token expires, exchange the refresh token for a new access token so your app keeps working without sending the merchant back through authorization.

Anchor to Exchange the refresh tokenExchange the refresh token

Send the stored refresh_token to the token endpoint before expires_in seconds elapse. The response contains a new access token and a new refresh token, each with updated expiry times, so store both and discard the old pair.

Request

curl -X POST \

https://{shop}.myshopify.com/admin/oauth/access_token \

-H 'Content-Type: application/x-www-form-urlencoded' \

-H 'Accept: application/json' \

-d 'client_id={client_id}' \

-d 'client_secret={client_secret}' \

-d 'grant_type=refresh_token' \

-d 'refresh_token={refresh_token}'

Response

{

"access_token": "shpat_yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy",

"expires_in": 3600,

"refresh_token": "shprt_zzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz",

"refresh_token_expires_in": 7776000,

"scope": "write_products,read_orders"

}

/node/index.js

100

101

102

103

104

105

106

107

108

109

110

111

112

113

114

115

116

117

118

119

120

121

122

123

124

125

126

127

128

129

130

131

132

133

134

135

136

137

138

139

140

141

142

143

144

145

146

147

148

149

150

151

152

153

154

155

156

157

158

159

160

161

162

163

164

165

166

167

168

169

170

171

172

173

174

175

176

177

178

179

180

181

182

183

184

185

186

187

188

189

190

191

192

193

194

195

196

197

198

199

200

201

202

203

204

205

206

207

208

209

210

211

212

213

214

215

216

217

218

219

220

221

222

223

224

225

226

227

228

229

230

231

232

233

234

235

236

237

238

239

240

241

242

243

244

245

246

247

248

249

250

251

252

253

254

255

256

257

258

259

260

261

262

263

264

265

266

267

268

269

270

271

272

273

274

275

276

277

278

279

280

281

282

283

284

285

286

287

288

289

290

291

292

293

294

295

296

297

import express from 'express';

import crypto from 'crypto';

import cookieParser from 'cookie-parser';

import * as dotenv from 'dotenv';

dotenv.config();

// Falls back to a random secret for local dev. Set COOKIE_SECRET in production

// so signed cookies stay valid across restarts and deployments.

const COOKIE_SECRET = process.env.COOKIE_SECRET || crypto.randomBytes(64).toString('hex');

const app = express();

app.use(cookieParser(COOKIE_SECRET));

const CLIENT_ID = process.env.SHOPIFY_CLIENT_ID;

const CLIENT_SECRET = process.env.SHOPIFY_CLIENT_SECRET;

const REDIRECT_URI = process.env.REDIRECT_URI;

const SCOPES = process.env.SCOPES || 'read_products,write_orders';

// In-memory token store (use a database in production)

const tokenStore = {};

// Send cookies only over HTTPS in production; over plain HTTP on localhost in

// dev. httpOnly + sameSite protect them the rest of the time.

const cookieOptions = {

signed: true,

httpOnly: true,

sameSite: 'lax',

secure: process.env.NODE_ENV === 'production',

};

// A valid expiring-token response includes expires_in (seconds until the access

// token expires). Return null when it's absent or non-positive: treat the token

// as non-expiring and never refresh it. Storing Date.now() instead would make

// the next request refresh a token that has no refresh_token — a permanent 401.

function expiresAtFrom(expiresIn) {

const seconds = Number(expiresIn);

return seconds > 0 ? Date.now() + seconds * 1000 : null;

}

function isValidShopDomain(shop) {

return /^[a-zA-Z0-9][a-zA-Z0-9\-]*\.myshopify\.com$/.test(shop);

}

// Node's fetch has no timeout, so a stalled connection to Shopify would hang a

// request until the client gives up. Give every call a deadline, and tag transport

// failures so callers can tell "Shopify said no" from "we never reached Shopify".

// fetch rejects only on a transport failure or this timeout: every HTTP status,

// including 5xx, resolves and is the caller's to handle.

const SHOPIFY_TIMEOUT_MS = 30_000;

class ShopifyUnreachable extends Error {}

async function shopifyFetch(url, options) {

try {

return await fetch(url, {

...options,

signal: AbortSignal.timeout(SHOPIFY_TIMEOUT_MS),

});

} catch (cause) {

throw new ShopifyUnreachable(`Could not reach ${new URL(url).hostname}`, { cause });

}

app.get('/install', (req, res) => {

const { shop } = req.query;

if (!isValidShopDomain(shop)) {

return res.status(400).send('Invalid shop domain');

}

const nonce = crypto.randomBytes(16).toString('hex');

// Store the nonce in a signed cookie so you can verify it against the callback

res.cookie('oauth_state', nonce, cookieOptions);

const authUrl = `https://${shop}/admin/oauth/authorize?` +

new URLSearchParams({

client_id: CLIENT_ID,

scope: SCOPES,

redirect_uri: REDIRECT_URI,

state: nonce,

});

res.redirect(authUrl);

});

app.get('/callback', async (req, res) => {

const { code, hmac, shop, state } = req.query;

if (!state || state !== req.signedCookies.oauth_state) {

return res.status(403).send('Invalid state parameter');

}

res.clearCookie('oauth_state');

const params = Object.fromEntries(

Object.entries(req.query).filter(([key]) => key !== 'hmac')

);

const message = Object.entries(params).sort().map(([k, v]) => `${k}=${v}`).join('&');

const digest = crypto.createHmac('sha256', CLIENT_SECRET).update(message).digest('hex');

const digestBuf = Buffer.from(digest);

const hmacBuf = Buffer.from(String(hmac));

if (digestBuf.length !== hmacBuf.length || !crypto.timingSafeEqual(digestBuf, hmacBuf)) {

return res.status(403).send('Invalid HMAC');

}

if (!isValidShopDomain(shop)) {

return res.status(400).send('Invalid shop domain');

}

const tokenResponse = await shopifyFetch(`https://${shop}/admin/oauth/access_token`, {

method: 'POST',

headers: {

'Content-Type': 'application/x-www-form-urlencoded',

Accept: 'application/json',

body: new URLSearchParams({

client_id: CLIENT_ID,

client_secret: CLIENT_SECRET,

code,

expiring: '1',

}),

});

if (!tokenResponse.ok) {

return res.status(403).send('Token exchange failed');

}

const { access_token, refresh_token, scope, expires_in } = await tokenResponse.json();

const granted = scope.split(',');

// A write_* grant includes its matching read_* scope, so Shopify may return

// only the write scope. Treat a requested read_* as satisfied by its write_*.

const missing = SCOPES.split(',').filter(s =>

!granted.includes(s) &&

!(s.startsWith('read_') && granted.includes(`write_${s.slice(5)}`))

);

if (missing.length > 0) return res.status(403).send(`Missing scopes: ${missing.join(', ')}`);

// Store tokens server-side, keyed by shop (use a database in production).

// Track when the access token expires so requests can refresh it in time.

tokenStore[shop] = {

access_token,

refresh_token,

expires_at: expiresAtFrom(expires_in),

};

// Set a signed session cookie so subsequent requests can identify the shop

res.cookie('shop', shop, cookieOptions);

res.json({ message: 'App installed', shop, scope });

});

// Exchange the stored refresh token for a new access token. The return value

// tells the caller how to react, and matches the refresh error handling used

// across grant types:

// 'refreshed' — got a new access token

//   'reauthorize' — a 401 means the refresh token is terminal (expired, revoked,

// replayed after the one-hour retry window, or the app was

// uninstalled); send the merchant back through OAuth

//   'retry'       — a transient failure (network, timeout, 5xx, 429); safe to

// retry later with the same refresh token

//   'failed'      — any other non-OK status, such as a malformed request or bad

//                   client credentials; retrying sends the identical request and

// fails the same way, so surface it instead of hiding it

async function refreshAccessToken(shop) {

const stored = tokenStore[shop];

if (!stored?.refresh_token) return 'reauthorize';

let response;

try {

response = await shopifyFetch(`https://${shop}/admin/oauth/access_token`, {

method: 'POST',

headers: {

'Content-Type': 'application/x-www-form-urlencoded',

Accept: 'application/json',

body: new URLSearchParams({

client_id: CLIENT_ID,

client_secret: CLIENT_SECRET,

grant_type: 'refresh_token',

refresh_token: stored.refresh_token,

}),

});

} catch (error) {

// Only a transport failure or timeout becomes 'retry': the request never

// reached Shopify, so the refresh token is untouched and a later attempt is

// safe. Anything else is a bug in this code — let it surface.

if (!(error instanceof ShopifyUnreachable)) throw error;

return 'retry';

}

// A 401 is terminal: drop the dead token so the merchant reinstalls.

if (response.status === 401) {

delete tokenStore[shop];

return 'reauthorize';

}

// Only a rate limit or a server fault is worth retrying. Treating every other

// non-OK status as transient would retry an unrecoverable refresh forever —

// a 400 for a malformed body, or a 403 for bad client credentials, returns the

// same response no matter how long you wait.

if (response.status === 429 || response.status >= 500) return 'retry';

if (!response.ok) return 'failed';

const { access_token, refresh_token, expires_in } = await response.json();

tokenStore[shop] = {

access_token,

refresh_token,

expires_at: expiresAtFrom(expires_in),

};

return 'refreshed';

}

app.get('/products', async (req, res) => {

const shop = req.signedCookies.shop;

if (!shop) return res.status(401).send('Not authenticated');

let stored = tokenStore[shop];

if (!stored) return res.status(401).send('Not authenticated');

// Expiring access tokens are short-lived. Refresh ~60 seconds before the token

// actually expires so a request never goes out with a token that lapses

// mid-flight.

if (stored.expires_at && Date.now() >= stored.expires_at - 60 * 1000) {

const result = await refreshAccessToken(shop);

if (result === 'reauthorize') {

return res.status(401).send('Reauthorization required');

}

if (result === 'retry') {

return res.status(503).send('Token refresh failed, try again');

}

if (result === 'failed') {

// Not the merchant's problem and not worth retrying: fix the app's request

// or credentials. Don't fall through — `stored` still holds the token that

// is about to expire.

return res.status(502).send('Token refresh failed');

}

stored = tokenStore[shop];

}

const callAdminApi = (accessToken) =>

shopifyFetch(`https://${shop}/admin/api/2026-04/graphql.json`, {

method: 'POST',

headers: {

'Content-Type': 'application/json',

'X-Shopify-Access-Token': accessToken,

body: JSON.stringify({ query: '{ products(first: 5) { edges { node { id handle } } } }' }),

});

let response = await callAdminApi(stored.access_token);

// Shopify rejected the access token: it was revoked, the app's access scopes

// changed, or it lapsed sooner than expires_in implied. This app runs outside

// the Shopify admin, so it has no ID token to exchange — the refresh token is

// the only way back. Try it once, then give up rather than sending the same

// rejected token again on every later request.

if (response.status === 401) {

const result = await refreshAccessToken(shop);

if (result === 'retry') {

// Transient: the refresh token is untouched, so a later attempt is fine.

return res.status(503).send('Token refresh failed, try again');

}

if (result === 'failed') {

return res.status(502).send('Token refresh failed');

}

if (result !== 'refreshed') {

// Drop the rejected token so the next request doesn't send it again.

delete tokenStore[shop];

return res.status(401).send('Reauthorization required');

}

response = await callAdminApi(tokenStore[shop].access_token);

// Retry once, not in a loop. A freshly refreshed token that's also rejected

// means something is wrong beyond a lapsed credential, so stop and send the

// merchant back through OAuth.

if (response.status === 401) {

delete tokenStore[shop];

return res.status(401).send('Reauthorization required');

}

// Forward Shopify's status. Answering a rate limit or an outage with a 200 and

// an error body in it would tell the client the request succeeded.

res.status(response.status).json(await response.json());

});

// The routes above let a transport failure or timeout propagate. The request never

// reached Shopify, so nothing was consumed and the caller can try again: 503 says

// that, while the stack trace Express would otherwise return says the app is broken.

app.use((err, req, res, next) => {

if (err instanceof ShopifyUnreachable) {

return res.status(503).send('Could not reach Shopify, try again');

}

next(err);

});

app.listen(3000, () => console.log('Server running on http://localhost:3000'));

Anchor to Handle refresh failuresHandle refresh failures

Treat a successful rotation as consuming the previous offline refresh token. Refreshes are resilient to ambiguous failures: if a refresh request times out, hits a network error, or returns a transient 5xx, retry promptly with the same refresh_token, and the repeated request returns the same rotated credentials rather than issuing another set. Don't rely on a fixed retry-window duration. If the refresh token is expired or otherwise invalid, Shopify returns 401 Unauthorized with {"error": "invalid_request"}. Clear the stored token pair and send the merchant back through authorization to mint a new one. For the full error behavior, see Refresh an expiring offline token.

/node/index.js

100

101

102

103

104

105

106

107

108

109

110

111

112

113

114

115

116

117

118

119

120

121

122

123

124

125

126

127

128

129

130

131

132

133

134

135

136

137

138

139

140

141

142

143

144

145

146

147

148

149

150

151

152

153

154

155

156

157

158

159

160

161

162

163

164

165

166

167

168

169

170

171

172

173

174

175

176

177

178

179

180

181

182

183

184

185

186

187

188

189

190

191

192

193

194

195

196

197

198

199

200

201

202

203

204

205

206

207

208

209

210

211

212

213

214

215

216

217

218

219

220

221

222

223

224

225

226

227

228

229

230

231

232

233

234

235

236

237

238

239

240

241

242

243

244

245

246

247

248

249

250

251

252

253

254

255

256

257

258

259

260

261

262

263

264

265

266

267

268

269

270

271

272

273

274

275

276

277

278

279

280

281

282

283

284

285

286

287

288

289

290

291

292

293

294

295

296

297

import express from 'express';

import crypto from 'crypto';

import cookieParser from 'cookie-parser';

import * as dotenv from 'dotenv';

dotenv.config();

// Falls back to a random secret for local dev. Set COOKIE_SECRET in production

// so signed cookies stay valid across restarts and deployments.

const COOKIE_SECRET = process.env.COOKIE_SECRET || crypto.randomBytes(64).toString('hex');

const app = express();

app.use(cookieParser(COOKIE_SECRET));

const CLIENT_ID = process.env.SHOPIFY_CLIENT_ID;

const CLIENT_SECRET = process.env.SHOPIFY_CLIENT_SECRET;

const REDIRECT_URI = process.env.REDIRECT_URI;

const SCOPES = process.env.SCOPES || 'read_products,write_orders';

// In-memory token store (use a database in production)

const tokenStore = {};

// Send cookies only over HTTPS in production; over plain HTTP on localhost in

// dev. httpOnly + sameSite protect them the rest of the time.

const cookieOptions = {

signed: true,

httpOnly: true,

sameSite: 'lax',

secure: process.env.NODE_ENV === 'production',

};

// A valid expiring-token response includes expires_in (seconds until the access

// token expires). Return null when it's absent or non-positive: treat the token

// as non-expiring and never refresh it. Storing Date.now() instead would make

// the next request refresh a token that has no refresh_token — a permanent 401.

function expiresAtFrom(expiresIn) {

const seconds = Number(expiresIn);

return seconds > 0 ? Date.now() + seconds * 1000 : null;

}

function isValidShopDomain(shop) {

return /^[a-zA-Z0-9][a-zA-Z0-9\-]*\.myshopify\.com$/.test(shop);

}

// Node's fetch has no timeout, so a stalled connection to Shopify would hang a

// request until the client gives up. Give every call a deadline, and tag transport

// failures so callers can tell "Shopify said no" from "we never reached Shopify".

// fetch rejects only on a transport failure or this timeout: every HTTP status,

// including 5xx, resolves and is the caller's to handle.

const SHOPIFY_TIMEOUT_MS = 30_000;

class ShopifyUnreachable extends Error {}

async function shopifyFetch(url, options) {

try {

return await fetch(url, {

...options,

signal: AbortSignal.timeout(SHOPIFY_TIMEOUT_MS),

});

} catch (cause) {

throw new ShopifyUnreachable(`Could not reach ${new URL(url).hostname}`, { cause });

}

app.get('/install', (req, res) => {

const { shop } = req.query;

if (!isValidShopDomain(shop)) {

return res.status(400).send('Invalid shop domain');

}

const nonce = crypto.randomBytes(16).toString('hex');

// Store the nonce in a signed cookie so you can verify it against the callback

res.cookie('oauth_state', nonce, cookieOptions);

const authUrl = `https://${shop}/admin/oauth/authorize?` +

new URLSearchParams({

client_id: CLIENT_ID,

scope: SCOPES,

redirect_uri: REDIRECT_URI,

state: nonce,

});

res.redirect(authUrl);

});

app.get('/callback', async (req, res) => {

const { code, hmac, shop, state } = req.query;

if (!state || state !== req.signedCookies.oauth_state) {

return res.status(403).send('Invalid state parameter');

}

res.clearCookie('oauth_state');

const params = Object.fromEntries(

Object.entries(req.query).filter(([key]) => key !== 'hmac')

);

const message = Object.entries(params).sort().map(([k, v]) => `${k}=${v}`).join('&');

const digest = crypto.createHmac('sha256', CLIENT_SECRET).update(message).digest('hex');

const digestBuf = Buffer.from(digest);

const hmacBuf = Buffer.from(String(hmac));

if (digestBuf.length !== hmacBuf.length || !crypto.timingSafeEqual(digestBuf, hmacBuf)) {

return res.status(403).send('Invalid HMAC');

}

if (!isValidShopDomain(shop)) {

return res.status(400).send('Invalid shop domain');

}

const tokenResponse = await shopifyFetch(`https://${shop}/admin/oauth/access_token`, {

method: 'POST',

headers: {

'Content-Type': 'application/x-www-form-urlencoded',

Accept: 'application/json',

body: new URLSearchParams({

client_id: CLIENT_ID,

client_secret: CLIENT_SECRET,

code,

expiring: '1',

}),

});

if (!tokenResponse.ok) {

return res.status(403).send('Token exchange failed');

}

const { access_token, refresh_token, scope, expires_in } = await tokenResponse.json();

const granted = scope.split(',');

// A write_* grant includes its matching read_* scope, so Shopify may return

// only the write scope. Treat a requested read_* as satisfied by its write_*.

const missing = SCOPES.split(',').filter(s =>

!granted.includes(s) &&

!(s.startsWith('read_') && granted.includes(`write_${s.slice(5)}`))

);

if (missing.length > 0) return res.status(403).send(`Missing scopes: ${missing.join(', ')}`);

// Store tokens server-side, keyed by shop (use a database in production).

// Track when the access token expires so requests can refresh it in time.

tokenStore[shop] = {

access_token,

refresh_token,

expires_at: expiresAtFrom(expires_in),

};

// Set a signed session cookie so subsequent requests can identify the shop

res.cookie('shop', shop, cookieOptions);

res.json({ message: 'App installed', shop, scope });

});

// Exchange the stored refresh token for a new access token. The return value

// tells the caller how to react, and matches the refresh error handling used

// across grant types:

// 'refreshed' — got a new access token

// 'reauthorize' — a 401 means the refresh token is terminal (expired, revoked,

// replayed after the one-hour retry window, or the app was

// uninstalled); send the merchant back through OAuth

// 'retry' — a transient failure (network, timeout, 5xx, 429); safe to

// retry later with the same refresh token

// 'failed' — any other non-OK status, such as a malformed request or bad

// client credentials; retrying sends the identical request and

// fails the same way, so surface it instead of hiding it

async function refreshAccessToken(shop) {

const stored = tokenStore[shop];

if (!stored?.refresh_token) return 'reauthorize';

let response;

try {

response = await shopifyFetch(`https://${shop}/admin/oauth/access_token`, {

method: 'POST',

headers: {

'Content-Type': 'application/x-www-form-urlencoded',

Accept: 'application/json',

body: new URLSearchParams({

client_id: CLIENT_ID,

client_secret: CLIENT_SECRET,

grant_type: 'refresh_token',

refresh_token: stored.refresh_token,

}),

});

} catch (error) {

// Only a transport failure or timeout becomes 'retry': the request never

// reached Shopify, so the refresh token is untouched and a later attempt is

// safe. Anything else is a bug in this code — let it surface.

if (!(error instanceof ShopifyUnreachable)) throw error;

return 'retry';

}

// A 401 is terminal: drop the dead token so the merchant reinstalls.

if (response.status === 401) {

delete tokenStore[shop];

return 'reauthorize';

}

// Only a rate limit or a server fault is worth retrying. Treating every other

// non-OK status as transient would retry an unrecoverable refresh forever —

// a 400 for a malformed body, or a 403 for bad client credentials, returns the

// same response no matter how long you wait.

if (response.status === 429 || response.status >= 500) return 'retry';

if (!response.ok) return 'failed';

const { access_token, refresh_token, expires_in } = await response.json();

tokenStore[shop] = {

access_token,

refresh_token,

expires_at: expiresAtFrom(expires_in),

};

return 'refreshed';

}

app.get('/products', async (req, res) => {

const shop = req.signedCookies.shop;

if (!shop) return res.status(401).send('Not authenticated');

let stored = tokenStore[shop];

if (!stored) return res.status(401).send('Not authenticated');

// Expiring access tokens are short-lived. Refresh ~60 seconds before the token

// actually expires so a request never goes out with a token that lapses

// mid-flight.

if (stored.expires_at && Date.now() >= stored.expires_at - 60 * 1000) {

const result = await refreshAccessToken(shop);

if (result === 'reauthorize') {

return res.status(401).send('Reauthorization required');

}

if (result === 'retry') {

return res.status(503).send('Token refresh failed, try again');

}

if (result === 'failed') {

// Not the merchant's problem and not worth retrying: fix the app's request

// or credentials. Don't fall through — `stored` still holds the token that

// is about to expire.

return res.status(502).send('Token refresh failed');

}

stored = tokenStore[shop];

}

const callAdminApi = (accessToken) =>

shopifyFetch(`https://${shop}/admin/api/2026-04/graphql.json`, {

method: 'POST',

headers: {

'Content-Type': 'application/json',

'X-Shopify-Access-Token': accessToken,

body: JSON.stringify({ query: '{ products(first: 5) { edges { node { id handle } } } }' }),

});

let response = await callAdminApi(stored.access_token);

// Shopify rejected the access token: it was revoked, the app's access scopes

// changed, or it lapsed sooner than expires_in implied. This app runs outside

// the Shopify admin, so it has no ID token to exchange — the refresh token is

// the only way back. Try it once, then give up rather than sending the same

// rejected token again on every later request.

if (response.status === 401) {

const result = await refreshAccessToken(shop);

if (result === 'retry') {

// Transient: the refresh token is untouched, so a later attempt is fine.

return res.status(503).send('Token refresh failed, try again');

}

if (result === 'failed') {

return res.status(502).send('Token refresh failed');

}

if (result !== 'refreshed') {

// Drop the rejected token so the next request doesn't send it again.

delete tokenStore[shop];

return res.status(401).send('Reauthorization required');

}

response = await callAdminApi(tokenStore[shop].access_token);

// Retry once, not in a loop. A freshly refreshed token that's also rejected

// means something is wrong beyond a lapsed credential, so stop and send the

// merchant back through OAuth.

if (response.status === 401) {

delete tokenStore[shop];

return res.status(401).send('Reauthorization required');

}

// Forward Shopify's status. Answering a rate limit or an outage with a 200 and

// an error body in it would tell the client the request succeeded.

res.status(response.status).json(await response.json());

});

// The routes above let a transport failure or timeout propagate. The request never

// reached Shopify, so nothing was consumed and the caller can try again: 503 says

// that, while the stack trace Express would otherwise return says the app is broken.

app.use((err, req, res, next) => {

if (err instanceof ShopifyUnreachable) {

return res.status(503).send('Could not reach Shopify, try again');

}

next(err);

});

app.listen(3000, () => console.log('Server running on http://localhost:3000'));

/node/index.js

100

101

102

103

104

105

106

107

108

109

110

111

112

113

114

115

116

117

118

119

120

121

122

123

124

125

126

127

128

129

130

131

132

133

134

135

136

137

138

139

140

141

142

143

144

145

146

147

148

149

150

151

152

153

154

155

156

157

158

159

160

161

162

163

164

165

166

167

168

169

170

171

172

173

174

175

176

177

178

179

180

181

182

183

184

185

186

187

188

189

190

191

192

193

194

195

196

197

198

199

200

201

202

203

204

205

206

207

208

209

210

211

212

213

214

215

216

217

218

219

220

221

222

223

224

225

226

227

228

229

230

231

232

233

234

235

236

237

238

239

240

241

242

243

244

245

246

247

248

249

250

251

252

253

254

255

256

257

258

259

260

261

262

263

264

265

266

267

268

269

270

271

272

273

274

275

276

277

278

279

280

281

282

283

284

285

286

287

288

289

290

291

292

293

294

295

296

297

import express from 'express';

import crypto from 'crypto';

import cookieParser from 'cookie-parser';

import * as dotenv from 'dotenv';

dotenv.config();

// Falls back to a random secret for local dev. Set COOKIE_SECRET in production

// so signed cookies stay valid across restarts and deployments.

const COOKIE_SECRET = process.env.COOKIE_SECRET || crypto.randomBytes(64).toString('hex');

const app = express();

app.use(cookieParser(COOKIE_SECRET));

const CLIENT_ID = process.env.SHOPIFY_CLIENT_ID;

const CLIENT_SECRET = process.env.SHOPIFY_CLIENT_SECRET;

const REDIRECT_URI = process.env.REDIRECT_URI;

const SCOPES = process.env.SCOPES || 'read_products,write_orders';

// In-memory token store (use a database in production)

const tokenStore = {};

// Send cookies only over HTTPS in production; over plain HTTP on localhost in

// dev. httpOnly + sameSite protect them the rest of the time.

const cookieOptions = {

signed: true,

httpOnly: true,

sameSite: 'lax',

secure: process.env.NODE_ENV === 'production',

};

// A valid expiring-token response includes expires_in (seconds until the access

// token expires). Return null when it's absent or non-positive: treat the token

// as non-expiring and never refresh it. Storing Date.now() instead would make

// the next request refresh a token that has no refresh_token — a permanent 401.

function expiresAtFrom(expiresIn) {

const seconds = Number(expiresIn);

return seconds > 0 ? Date.now() + seconds * 1000 : null;

}

function isValidShopDomain(shop) {

return /^[a-zA-Z0-9][a-zA-Z0-9\-]*\.myshopify\.com$/.test(shop);

}

// Node's fetch has no timeout, so a stalled connection to Shopify would hang a

// request until the client gives up. Give every call a deadline, and tag transport

// failures so callers can tell "Shopify said no" from "we never reached Shopify".

// fetch rejects only on a transport failure or this timeout: every HTTP status,

// including 5xx, resolves and is the caller's to handle.

const SHOPIFY_TIMEOUT_MS = 30_000;

class ShopifyUnreachable extends Error {}

async function shopifyFetch(url, options) {

try {

return await fetch(url, {

...options,

signal: AbortSignal.timeout(SHOPIFY_TIMEOUT_MS),

});

} catch (cause) {

throw new ShopifyUnreachable(`Could not reach ${new URL(url).hostname}`, { cause });

}

app.get('/install', (req, res) => {

const { shop } = req.query;

if (!isValidShopDomain(shop)) {

return res.status(400).send('Invalid shop domain');

}

const nonce = crypto.randomBytes(16).toString('hex');

// Store the nonce in a signed cookie so you can verify it against the callback

res.cookie('oauth_state', nonce, cookieOptions);

const authUrl = `https://${shop}/admin/oauth/authorize?` +

new URLSearchParams({

client_id: CLIENT_ID,

scope: SCOPES,

redirect_uri: REDIRECT_URI,

state: nonce,

});

res.redirect(authUrl);

});

app.get('/callback', async (req, res) => {

const { code, hmac, shop, state } = req.query;

if (!state || state !== req.signedCookies.oauth_state) {

return res.status(403).send('Invalid state parameter');

}

res.clearCookie('oauth_state');

const params = Object.fromEntries(

Object.entries(req.query).filter(([key]) => key !== 'hmac')

);

const message = Object.entries(params).sort().map(([k, v]) => `${k}=${v}`).join('&');

const digest = crypto.createHmac('sha256', CLIENT_SECRET).update(message).digest('hex');

const digestBuf = Buffer.from(digest);

const hmacBuf = Buffer.from(String(hmac));

if (digestBuf.length !== hmacBuf.length || !crypto.timingSafeEqual(digestBuf, hmacBuf)) {

return res.status(403).send('Invalid HMAC');

}

if (!isValidShopDomain(shop)) {

return res.status(400).send('Invalid shop domain');

}

const tokenResponse = await shopifyFetch(`https://${shop}/admin/oauth/access_token`, {

method: 'POST',

headers: {

'Content-Type': 'application/x-www-form-urlencoded',

Accept: 'application/json',

body: new URLSearchParams({

client_id: CLIENT_ID,

client_secret: CLIENT_SECRET,

code,

expiring: '1',

}),

});

if (!tokenResponse.ok) {

return res.status(403).send('Token exchange failed');

}

const { access_token, refresh_token, scope, expires_in } = await tokenResponse.json();

const granted = scope.split(',');

// A write_* grant includes its matching read_* scope, so Shopify may return

// only the write scope. Treat a requested read_* as satisfied by its write_*.

const missing = SCOPES.split(',').filter(s =>

!granted.includes(s) &&

!(s.startsWith('read_') && granted.includes(`write_${s.slice(5)}`))

);

if (missing.length > 0) return res.status(403).send(`Missing scopes: ${missing.join(', ')}`);

// Store tokens server-side, keyed by shop (use a database in production).

// Track when the access token expires so requests can refresh it in time.

tokenStore[shop] = {

access_token,

refresh_token,

expires_at: expiresAtFrom(expires_in),

};

// Set a signed session cookie so subsequent requests can identify the shop

res.cookie('shop', shop, cookieOptions);

res.json({ message: 'App installed', shop, scope });

});

// Exchange the stored refresh token for a new access token. The return value

// tells the caller how to react, and matches the refresh error handling used

// across grant types:

// 'refreshed' — got a new access token

// 'reauthorize' — a 401 means the refresh token is terminal (expired, revoked,

// replayed after the one-hour retry window, or the app was

// uninstalled); send the merchant back through OAuth

// 'retry' — a transient failure (network, timeout, 5xx, 429); safe to

// retry later with the same refresh token

// 'failed' — any other non-OK status, such as a malformed request or bad

// client credentials; retrying sends the identical request and

// fails the same way, so surface it instead of hiding it

async function refreshAccessToken(shop) {

const stored = tokenStore[shop];

if (!stored?.refresh_token) return 'reauthorize';

let response;

try {

response = await shopifyFetch(`https://${shop}/admin/oauth/access_token`, {

method: 'POST',

headers: {

'Content-Type': 'application/x-www-form-urlencoded',

Accept: 'application/json',

body: new URLSearchParams({

client_id: CLIENT_ID,

client_secret: CLIENT_SECRET,

grant_type: 'refresh_token',

refresh_token: stored.refresh_token,

}),

});

} catch (error) {

// Only a transport failure or timeout becomes 'retry': the request never

// reached Shopify, so the refresh token is untouched and a later attempt is

// safe. Anything else is a bug in this code — let it surface.

if (!(error instanceof ShopifyUnreachable)) throw error;

return 'retry';

}

// A 401 is terminal: drop the dead token so the merchant reinstalls.

if (response.status === 401) {

delete tokenStore[shop];

return 'reauthorize';

}

// Only a rate limit or a server fault is worth retrying. Treating every other

// non-OK status as transient would retry an unrecoverable refresh forever —

// a 400 for a malformed body, or a 403 for bad client credentials, returns the

// same response no matter how long you wait.

if (response.status === 429 || response.status >= 500) return 'retry';

if (!response.ok) return 'failed';

const { access_token, refresh_token, expires_in } = await response.json();

tokenStore[shop] = {

access_token,

refresh_token,

expires_at: expiresAtFrom(expires_in),

};

return 'refreshed';

}

app.get('/products', async (req, res) => {

const shop = req.signedCookies.shop;

if (!shop) return res.status(401).send('Not authenticated');

let stored = tokenStore[shop];

if (!stored) return res.status(401).send('Not authenticated');

// Expiring access tokens are short-lived. Refresh ~60 seconds before the token

// actually expires so a request never goes out with a token that lapses

// mid-flight.

if (stored.expires_at && Date.now() >= stored.expires_at - 60 * 1000) {

const result = await refreshAccessToken(shop);

if (result === 'reauthorize') {

return res.status(401).send('Reauthorization required');

}

if (result === 'retry') {

return res.status(503).send('Token refresh failed, try again');

}

if (result === 'failed') {

// Not the merchant's problem and not worth retrying: fix the app's request

// or credentials. Don't fall through — `stored` still holds the token that

// is about to expire.

return res.status(502).send('Token refresh failed');

}

stored = tokenStore[shop];

}

const callAdminApi = (accessToken) =>

shopifyFetch(`https://${shop}/admin/api/2026-04/graphql.json`, {

method: 'POST',

headers: {

'Content-Type': 'application/json',

'X-Shopify-Access-Token': accessToken,

body: JSON.stringify({ query: '{ products(first: 5) { edges { node { id handle } } } }' }),

});

let response = await callAdminApi(stored.access_token);

// Shopify rejected the access token: it was revoked, the app's access scopes

// changed, or it lapsed sooner than expires_in implied. This app runs outside

// the Shopify admin, so it has no ID token to exchange — the refresh token is

// the only way back. Try it once, then give up rather than sending the same

// rejected token again on every later request.

if (response.status === 401) {

const result = await refreshAccessToken(shop);

if (result === 'retry') {

// Transient: the refresh token is untouched, so a later attempt is fine.

return res.status(503).send('Token refresh failed, try again');

}

if (result === 'failed') {

return res.status(502).send('Token refresh failed');

}

if (result !== 'refreshed') {

// Drop the rejected token so the next request doesn't send it again.

delete tokenStore[shop];

return res.status(401).send('Reauthorization required');

}

response = await callAdminApi(tokenStore[shop].access_token);

// Retry once, not in a loop. A freshly refreshed token that's also rejected

// means something is wrong beyond a lapsed credential, so stop and send the

// merchant back through OAuth.

if (response.status === 401) {

delete tokenStore[shop];

return res.status(401).send('Reauthorization required');

}

// Forward Shopify's status. Answering a rate limit or an outage with a 200 and

// an error body in it would tell the client the request succeeded.

res.status(response.status).json(await response.json());

});

// The routes above let a transport failure or timeout propagate. The request never

// reached Shopify, so nothing was consumed and the caller can try again: 503 says

// that, while the stack trace Express would otherwise return says the app is broken.

app.use((err, req, res, next) => {

if (err instanceof ShopifyUnreachable) {

return res.status(503).send('Could not reach Shopify, try again');

}

next(err);

});

app.listen(3000, () => console.log('Server running on http://localhost:3000'));

Anchor to Tutorial complete!Tutorial complete!

Your app now completes the authorization code grant and holds an access token it can use against Shopify APIs.

Anchor to Next stepsNext steps

Manage your credentials

Find your client ID and secret, secure them, and rotate your client secret.

Query store data

Use your access token to query and mutate store data with the GraphQL Admin API.

Set up webhooks

Manage access scopes

Change your declared scopes after launch, and request or revoke optional scopes dynamically.

Delegate API access

Give subsystems scoped, limited access to Shopify APIs without sharing your app's full credentials.

Was this page helpful?

Anchor to What you'll learnWhat you'll learn

Requirements

Project

Anchor to Redirect to Shopify's authorization pageRedirect to Shopify's authorization page

Anchor to Build the authorization URLBuild the authorization URL

Anchor to Validate the callbackValidate the callback

Anchor to Verify the ,[object Object], parameterVerify the state parameter

Anchor to Verify the HMACVerify the HMAC

Anchor to Validate the ,[object Object], domainValidate the shop domain

Anchor to Exchange the code for an offline access tokenExchange the code for an offline access token

Anchor to Send the token requestSend the token request

Anchor to Confirm the granted scopesConfirm the granted scopes

Anchor to Store the tokensStore the tokens

Anchor to (Optional) Request an online access token(Optional) Request an online access token

Anchor to Add the per-user parameter to the authorization URLAdd the per-user parameter to the authorization URL

Anchor to Make authenticated API requestsMake authenticated API requests

Anchor to Add the access token headerAdd the access token header

Anchor to Refresh the access tokenRefresh the access token

Anchor to Exchange the refresh tokenExchange the refresh token

Anchor to Handle refresh failuresHandle refresh failures

Anchor to Tutorial complete!Tutorial complete!

Anchor to Next stepsNext steps

Anchor to Verify the ,[object Object], parameterVerify the `state` parameter

Anchor to Validate the ,[object Object], domainValidate the `shop` domain