> This page is for Developer.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.bigcommerce.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.bigcommerce.com/_mcp/server.

# Apps Quick Start

# BigCommerce Apps Quick Start

In this quick start tutorial, you will create a [single-click app](/developer/docs/integrations/apps/guide/types-of-apps) using [Node.js](https://nodejs.org/en/), [React](https://www.reactjs.org/), [Next.js](https://nextjs.org/), and [BigDesign](https://developer.bigcommerce.com/bigdesign).

## Prerequisites

To successfully complete this tutorial, you will need the following:

* [BigCommerce sandbox store](/developer/docs/overview/sandboxes) (required to develop and test apps)
* [Developer Portal Account](https://build.bigcommerce.com/) (required to register apps)
* Experience using [pnpm](https://pnpm.io/)
* Node.js 24 or later

## Get started

1. Start by forking the [starter-sc-app-next](https://github.com/bigcommerce-edu/starter-sc-app-next) repository.
2. Navigate to the root directory of your project and install packages.

```shell showLineNumbers={false}
pnpm install
```

3. Copy the sample environment file. You will fill in its values in a later step.

```shell showLineNumbers={false}
cp .env.example .env.local
```

## Expose your local server over HTTPS

You will need a publicly accessible HTTPS URL to connect the draft app to BigCommerce. BigCommerce calls your app back over the internet and renders it in a control panel iframe, so a bare `http://localhost:3000` will not work.

This tutorial uses [ngrok](https://ngrok.com/docs), a tool that lets you expose local servers like `localhost:3000` to the public internet over secure tunnels. The starter app also documents [VS Code port forwarding and GitHub Codespaces](https://github.com/bigcommerce-edu/starter-sc-app-next/blob/main/docs/LOCAL-SINGLE-CLICK-APP.md#exposing-localhost-over-https) as alternatives.

1. In a new terminal window, install [ngrok](https://www.npmjs.com/package/ngrok#usage) using Homebrew.

```shell showLineNumbers={false}
brew install ngrok/ngrok/ngrok
ngrok config add-authtoken <TOKEN>
```

> **Note**
>
> You can obtain your authtoken by going to [https://dashboard.ngrok.com/get-started/your-authtoken](https://dashboard.ngrok.com/get-started/your-authtoken).

2. Expose the web server to the internet.

```bash showLineNumbers={false}
cd ~/path/to/starter-sc-app-next # Make sure you're in your project directory.

ngrok http 3000              # Start the tunnel
```

3. Copy the `https://<subdomain>.ngrok-free.app` **Forwarding** URL. This tutorial refers to it as your app origin.

> **Note**
>
> Most free tunneling services issue a new URL every time you restart the tunnel. When the URL changes, you must update both `APP_ORIGIN` and the callback URLs in the Developer Portal, then restart the dev server. Keeping the tunnel running for the length of a work session saves a lot of re-editing.

## Register the app

Next, create a draft app profile in the [Developer Portal](https://build.bigcommerce.com/) using the following steps:

1. [Sign in to the Developer Portal](https://build.bigcommerce.com/).
2. Click **Create an app**.
3. Give the app a name.
4. Click **Technical**.
5. Enter the **Auth Callback URL** as `https://{app_origin}/api/app/auth`. For example, `https://12345.ngrok-free.app/api/app/auth`. You can get the `app_origin` from the terminal that is running `ngrok http 3000`.
6. Enter the **Load Callback URL** as `https://{app_origin}/api/app/load`.
7. Enter the **Uninstall Callback URL** as `https://{app_origin}/api/app/uninstall`.
8. If your app supports multiple users, locate the **App Features** section. Select **Multiple Users**, then enter the **Remove User Callback URL** as `https://{app_origin}/api/app/remove_user`.
9. Set the OAuth scopes the starter app requires: **Customers** `modify`, **Marketing** `modify`, **Channel Settings** `read-only`, **Channel Listings** `read-only`, **Information & Settings** `read-only`, and **App Extensions** `manage`. To learn more about the available OAuth scopes, see [OAuth scopes](/developer/docs/overview/api-fundamentals/api-accounts#oauth-scopes).
10. Click **Update & Close**.
11. Click **View Client ID** to view this app's client ID and client secret, or *app-level API account*.

Keep this tab open for the next step.

> **Note**
>
> The Auth callback URL must match `APP_ORIGIN` exactly. The app sends it back to BigCommerce as the OAuth `redirect_uri` during the token exchange, and BigCommerce rejects a mismatch.

> **Note**
>
> Scope changes only take effect for a store on the next install. If you change scopes later, uninstall and reinstall the app.

## Configure environment variables

After registering the draft app, add its credentials and app origin to your project's environment variables file.

1. Open the `.env.local` file you created in the root directory of your project.

2. Set the following variables.

**`.env.local`**

```shell title=".env.local" showLineNumbers={false}
# Get the Client ID and Secret from the Developer Portal
BIGCOMMERCE_CLIENT_ID={app client id}
BIGCOMMERCE_CLIENT_SECRET={app secret}

# Your public HTTPS tunnel URL, with no trailing slash
APP_ORIGIN=https://{app_origin}

# Signs this app's own session cookie
SESSION_SECRET={secret}

# Encrypts stored store access tokens at rest
CREDENTIALS_ENCRYPTION_KEY={secret}

# Look up a per-store API token from durable storage
DATA_MODE=MULTITENANT

# Store credentials in a local SQLite file
CREDENTIALS_STORE_DRIVER=SQLITE
```

[See code in GitHub](https://github.com/bigcommerce-edu/starter-sc-app-next/blob/main/.env.example)

3. Replace the `BIGCOMMERCE_CLIENT_ID` and `BIGCOMMERCE_CLIENT_SECRET` with the app's client ID and client secret from the [Developer Portal](https://build.bigcommerce.com/).

4. Update `APP_ORIGIN` with your tunnel URL, omitting any trailing slash. You can get it from the terminal that is running `ngrok http 3000`.

5. Generate the `SESSION_SECRET` and `CREDENTIALS_ENCRYPTION_KEY` values.

> **Note**
>
> **Secret generation**
>
> * Each secret should be at least 32 random bytes.
> * You can generate a random key using the following command in your terminal:
>
> ```shell showLineNumbers={false}
> openssl rand -base64 32
> ```
>
> Run the command once per variable so the two secrets get different values. `SESSION_SECRET` signs this app's own session cookie, and `CREDENTIALS_ENCRYPTION_KEY` encrypts stored store access tokens at rest. Neither is interchangeable with `BIGCOMMERCE_CLIENT_SECRET`, which only verifies BigCommerce's inbound signed payloads.

> **Note**
>
> Ensure not to share these keys publicly. If you change `CREDENTIALS_ENCRYPTION_KEY`, previously stored tokens can no longer be decrypted — delete `data/credentials.sqlite` and reinstall the app.

6. Set `DATA_MODE` to `MULTITENANT`. This scopes every request to a store through the `/store/[storeHash]` route segment, authenticates it with the app's session cookie, and sources API tokens from the credentials store rather than mock or static data.

7. Leave `CREDENTIALS_STORE_DRIVER` set to `SQLITE`. The database is a plain file at `./data/credentials.sqlite`, created automatically on first use and gitignored. No migration step or external service is needed.

> **Note**
>
> SQLite is a local development choice only. Because it is a single file on one machine's disk, it cannot be shared across the multiple instances a real deployment runs. For a hosted environment, see the starter app's [Vercel deployment guide](https://github.com/bigcommerce-edu/starter-sc-app-next/blob/main/docs/VERCEL-DEPLOYMENT.md).

## Start dev environment

In a separate terminal from `ngrok`, start the app's dev environment.

```shell showLineNumbers={false}
pnpm dev
```

> **Note**
>
> Restart the dev server after any change to `.env.local`. A running server does not pick up environment variable changes, and `APP_ORIGIN` is read at startup to allow-list Server Action origins.

> **Note**
>
> #### Ngrok configuration
>
> Although you can use the `ngrok` npm package without creating an account, any unauthenticated tunnels you create will expire after two hours. For the best development experience, [create a free ngrok account](https://dashboard.ngrok.com/signup), [find your ngrok authtoken](https://dashboard.ngrok.com/get-started/your-authtoken), and [add the authtoken](https://ngrok.com/docs#getting-started-authtoken) to your global `ngrok` configuration.

## Install the app

Finally, install the draft app on any store registered to the same email as your [Developer Portal](https://build.bigcommerce.com/apps) account using the following steps:

1. Confirm the tunnel is up and public by opening your app origin in a browser. In `MULTITENANT` mode, you should see the "unauthorized" root route warning rather than an error. That means the app is reachable and correctly refusing to serve an unscoped route.
2. Sign in to the store, navigate to **Apps** > [**Develop**](https://login.bigcommerce.com/deep-links/manage/marketplace/apps/develop), and install the app, then approve the requested scopes.
3. If everything is configured correctly, BigCommerce calls `/api/app/auth`, which exchanges the code for a token, saves the store, mints a session cookie, and redirects into `/store/{store_hash}/`. The app then renders inside the control panel iframe.
4. Navigate back to **My Apps** to see the list of installed apps.
5. Click **Launch** on the draft app to test the `/api/app/load` callback, which verifies BigCommerce's signed payload and issues a fresh session.
6. Navigate back to **My Apps** and click **Uninstall** to test the `/api/app/uninstall` callback.

Congrats! You've created and installed a BigCommerce draft app.

> **Note**
>
> #### Becoming a partner
>
> Interested in sharing or selling your app? Learn more about [becoming a BigCommerce partner](https://www.bigcommerce.com/partners/become-a-partner) and [getting your app approved](/developer/docs/integrations/apps/guide/approval-requirements).

## Next steps

* [Learn more about building apps](/developer/docs/integrations/getting-started)
* [Apply to become a BigCommerce partner](https://www.bigcommerce.com/partners/become-a-partner)
* [Check out the BC App Marketplace approval requirements](/developer/docs/integrations/apps/guide/approval-requirements)

## Resources

* [BC App Marketplace](https://www.bigcommerce.com/apps/)
* [Guide to API Accounts](/developer/docs/overview/api-fundamentals/api-accounts#api-accounts)
* [Testing locally with ngrok](/developer/docs/integrations/apps/guide#testing-locally-with-ngrok)
* [Types of apps](/developer/docs/integrations/apps/guide/types-of-apps)
* [Becoming a partner](/developer/docs/overview/quick-start)