Skip to content
Tutorials Center
My learning

Topics

Lesson 9 of 28 ยท Apps and OAuth

App Types and the OAuth Flow

Understand BigCommerce app types, the Developer Portal, the auth, load and uninstall callbacks, the authorization code exchange and signed_payload_jwt checks.

A store-level API account is perfect for your own scripts. It is the wrong tool when you want many merchants to use your software: you cannot ask each one to create an account and paste a secret into your site. For that, BigCommerce has apps. An app is registered once with the platform, a merchant installs it with a click and approves the permissions it asks for, and the platform hands your server a token for that one store.

This lesson explains the app types, what you configure in the Developer Portal, the three callbacks the platform calls, and the OAuth authorization code exchange in detail, including how to verify the signed payload the platform sends when the app is opened. The real calls and URLs are read-only. The runnable stand-ins are Node.js programs that simulate the platform and your app, so you can watch each step and each failure. The simulated platform is ours, not BigCommerce's; it follows the same sequence but leaves out many production details.

App types

You will meet these words while planning:

  • Single-click app: the merchant installs it from the control panel or the App Marketplace with one click. The platform runs the OAuth flow for you. This is the standard kind of app and the one this course builds.
  • Draft app: an app you register for development and testing. It is installable only on stores you control (such as a sandbox store), which lets you iterate before submitting anything for review.
  • Marketplace app: an app listed in the App Marketplace after review. Listing is optional; you can also distribute an unlisted app by link to specific merchants.
  • Store-level API account: not an app at all, as covered in API Accounts, Tokens and Scopes.

An app can also be a pure server-side integration that never shows a screen, or it can show an interface inside the control panel. That interface is the subject of Building an App Backend.

The Developer Portal and the callbacks

You create and manage apps in the Developer Portal. For an app you fill in a name, the OAuth scopes it needs (apply least privilege, exactly as for API accounts) and a set of callback URLs on your own server. The portal shows the app's client id and client secret. The secret belongs on your server only.

Three callbacks matter, plus an optional fourth:

Callback When the platform calls it What your server does
Auth callback Right after a merchant approves the install Exchanges the temporary code for a token and saves it
Load callback Each time the merchant opens the app in the control panel Verifies the signed payload and shows the app
Uninstall callback When the merchant removes the app Deletes the store's data and token
Remove user callback (optional) When a store owner revokes a user's access to the app Deletes that user's access in your app

All callback URLs must be HTTPS and reachable from the internet. During local development you usually expose your machine with a tunnel and register the tunnel address on a draft app.

The authorization code exchange

The install sequence is the standard OAuth authorization code grant. In words: the platform sends the merchant's browser to your auth callback with a short-lived, single-use code; your server trades that code plus your secret for a long-lived access token, over a direct server-to-server call. The token never passes through the browser.

sequenceDiagram
    participant M as Merchant
    participant BC as BigCommerce
    participant A as Your app server
    M->>BC: Click Install, approve scopes
    BC->>M: Redirect to your auth callback<br/>with code, scope, context
    M->>A: GET /auth?code=...&scope=...&context=stores/abc
    A->>BC: POST token request<br/>(client id, secret, code, scope, context)
    BC-->>A: access_token, scope, context, user
    A->>A: Save token for store abc
    A->>M: Show success page

The code travels through the browser; the token travels only between servers.

The callback request carries three values you must handle: code, scope (the scopes actually granted) and context (the store, in the form stores/<hash>). Your server then sends a POST to the platform's token endpoint at the login service (read-only):

HTTP
POST https://login.bigcommerce.com/oauth2/token
Content-Type: application/json

{
  "client_id": "<your client id>",
  "client_secret": "<your client secret>",
  "code": "<code from the callback>",
  "scope": "<scope string from the callback>",
  "grant_type": "authorization_code",
  "redirect_uri": "https://app.example.com/auth",
  "context": "stores/abc123"
}

A success response includes the access_token, the granted scope, the context and basic details of the installing user. From then on you call that store's APIs with the token, exactly like in the REST lessons, using the store hash taken from context.

Several safety rules follow from this design:

  • Verify the granted scope. The merchant might approve fewer scopes than you asked for, or your registration might have changed. If the scopes you need are missing, fail clearly instead of crashing later.
  • Treat a code as single-use. A second exchange with the same code must fail. If your handler can be called twice (a browser refresh), make it safe to repeat without creating duplicate records.
  • Never log the secret or the token.
  • Know where state fits. A state value protects flows that your own site starts, such as a "connect your store" button on your website: you generate a random value, remember it, and accept the callback only if it comes back unchanged. A marketplace install is started by BigCommerce, so there is no value of yours to compare; there the protection comes from the secret-bearing exchange. The stand-in below shows both.

Simulating the install

The program simulates the platform and your app. The platform issues single-use codes and checks the secret; the app handles both a platform-started install and a self-started connection with a state check. Everything here is a model: names of fields follow the real flow, but there is no network, user interface or persistence.

Node.js Simulate the OAuth install, step by step

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Case A installs, and repeating the same callback fails because the code is single-use. Case B shows the scope guard stopping an install that would not work. Case C rejects a forged state and then accepts the real one. In a real app, a repeated callback would first look up whether the store is already installed and answer with a friendly page.

The load callback and signed_payload_jwt

Installing happens once; opening happens all the time. Each time a merchant opens your app in the control panel, the platform loads your load callback URL and adds a signed_payload_jwt query parameter. It is a JSON Web Token: three base64url parts (header, claims, signature) joined with dots. The signature is an HMAC-SHA256 made with your client secret, so only the platform and you can produce or check it.

Do not trust the request just because it arrived at your URL. Verify the token before you show anything:

  1. Check the signature with your client secret (use a constant-time comparison).
  2. Check that the aud claim equals your client id, so a token made for another app is refused.
  3. Check that the issuer is the platform and that the token has not expired.
  4. Read the store and user from the claims (typically a sub like stores/<hash> and a user object; confirm the exact claim names in the current documentation).

Only then do you look up that store's saved token and render the app. The second stand-in builds and verifies such a token using Node's crypto module. The claim values are made up, but the signing algorithm is the standard HS256 construction.

Node.js Verify a signed_payload_jwt

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Changing a claim without the secret breaks the signature, so the tampered token is rejected. A token signed with another key, meant for another app, past its expiry or not shaped like a JWT is rejected for its own reason. Every one of these checks maps to one line you would write in your load handler. In production, prefer a maintained JWT library over your own code, and still make sure it is configured to accept only the HS256 algorithm.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Why is the authorization code exchanged on the server instead of in the browser?

    The exchange proves the app's identity with its secret. Putting the secret in the browser would leak it.
  2. 2. What should your auth callback do if the granted scope lacks a scope you need?

    Checking the granted scope early prevents confusing 403 errors later.
  3. 3. Which callback receives the signed_payload_jwt?

    The load callback runs each time the app is opened and carries the signed payload that identifies the store and user.
  4. 4. When do you need a state value?

    State proves that a callback belongs to a flow you started. Marketplace installs are started by the platform.
  5. 5. A token verifies correctly but its aud claim is another app's id. What now?

    The audience check stops a valid token meant for a different app from being replayed against yours.

Summary

  • Apps let many merchants install your software; draft apps are for development, and listing in the marketplace is optional.
  • You register scopes and callback URLs in the Developer Portal; the client secret stays on your server.
  • The auth callback receives code, scope and context; your server exchanges the code for a token, and codes are single-use.
  • The load callback receives signed_payload_jwt: verify the signature, audience, issuer and expiry before showing anything.
  • Use state for flows you start yourself, and always clean up in the uninstall callback.

Next: Building an App Backend