Authentication

StockrHub uses Shopify’s session token authentication model for securing all API requests. This page explains how authentication works, from the initial OAuth installation flow to ongoing request verification.

Overview

Authentication in StockrHub has two phases:

1. OAuth Installation Flow — happens once when a merchant installs the app. Exchanges authorization codes for a permanent access token.
2. Session Token Verification — happens on every API request. Validates the JWT session token provided by Shopify App Bridge.

Shopify Session Tokens (JWT)

Once the app is installed and loaded inside Shopify admin, all API requests are authenticated using Shopify session tokens. These are JSON Web Tokens (JWT) generated by Shopify App Bridge v4 on the client side.

How Tokens Are Generated

1. The merchant opens StockrHub inside Shopify admin.
2. Shopify App Bridge v4 initializes and generates a session token.
3. The token is automatically included in every fetch request made by the app.
4. StockrHub’s middleware validates the token before processing the request.

Note

Session tokens are generated entirely by Shopify App Bridge. The app does not create or manage tokens directly — it only validates them on the server side.

Token Structure

A Shopify session token is a JWT with the following claims:

Claim	Description
iss	Issuer — the shop’s myshopify.com domain
dest	Destination — the shop’s domain
aud	Audience — the app’s API key
sub	Subject — the shop’s user ID
exp	Expiration — token expiry timestamp
nbf	Not Before — earliest valid timestamp
iat	Issued At — token creation timestamp
jti	JWT ID — unique token identifier
sid	Session ID — the Shopify session identifier

Token Validation (HMAC-SHA256)

StockrHub validates every session token using the following steps:

1. Extract the token from the Authorization: Bearer <token> header.
2. Decode the JWT header and payload (Base64URL decoding).
3. Verify the signature using HMAC-SHA256 with the app’s client secret as the signing key.
4. Check expiration — reject tokens where exp is in the past.
5. Verify the audience — ensure aud matches the app’s API key.
6. Verify the issuer — ensure iss matches a valid Shopify shop domain.

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Token Expiry and Refresh

• Session tokens are short-lived — they typically expire within minutes.
• App Bridge automatically refreshes tokens before they expire.
• If a token expires mid-request, the server returns a 401 Unauthorized response.
• App Bridge detects the 401 and retries the request with a fresh token.

Tip

You do not need to handle token refresh manually. Shopify App Bridge manages the entire token lifecycle automatically, including pre-emptive refresh before expiration.

OAuth Flow

The OAuth flow runs once during app installation to obtain a permanent access token for the shop.

Flow Steps

1. Install — the merchant clicks “Install” on the app listing in the Shopify App Store or is directed to the app’s install URL.

2. Authorize — StockrHub redirects the merchant to Shopify’s authorization page:

   https://{shop}.myshopify.com/admin/oauth/authorize?
     client_id={api_key}&
     scope={scopes}&
     redirect_uri={callback_url}&
     state={nonce}

3. Callback — after the merchant approves, Shopify redirects back to StockrHub’s callback URL with an authorization code:

   GET /auth/callback?code={authorization_code}&shop={shop}&state={nonce}&hmac={hmac}

4. Token Exchange — StockrHub exchanges the authorization code for a permanent access token:

   POST https://{shop}.myshopify.com/admin/oauth/access_token
   {
     "client_id": "{api_key}",
     "client_secret": "{api_secret}",
     "code": "{authorization_code}"
   }

5. Token Storage — the access token is encrypted using AES-256-GCM and stored in the D1 database. This token is used for all subsequent Shopify API calls on behalf of the shop.

Caution

The Shopify access token is stored encrypted at rest using AES-256-GCM. It is never exposed to the client side or included in API responses. Only the server-side Shopify client uses the decrypted token for Shopify API calls.

Middleware Verification

Every incoming API request passes through StockrHub’s authentication middleware before reaching the route handler:

1. Check for session token — the middleware looks for the Authorization: Bearer header.
2. Validate the token — performs JWT signature verification, expiry check, and audience validation.
3. Extract shop identity — determines which shop the request belongs to from the token claims.
4. Load shop context — retrieves the shop’s encrypted access token and configuration from the database.
5. Attach to request — adds the authenticated shop context to the request object for use by route handlers.

If any validation step fails, the middleware returns a 401 Unauthorized response and the request does not reach the route handler.

Security Considerations

• Tokens are never logged — session tokens and access tokens are excluded from all log output.
• HMAC verification on callbacks — the OAuth callback verifies the HMAC signature to prevent request forgery.
• Encrypted storage — Shopify access tokens are encrypted with AES-256-GCM before storage in D1.
• No external API access — the API only accepts requests from authenticated Shopify sessions, not from external clients.