> 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.

# Lab - Configure API Credentials and Channel

Plan: Composable Developer

Lesson 7 of 27 · 45 min

## **Preparing for Your Storefront Integration**

The BigCommerce APIs are the linchpin of your front-end's integration with the platform, so the first step for your development journey is to generate the appropriate access credentials to allow your application to access those APIs. We'll be generating two types of credentials: **Store-level v2/v3 API account** credentials and a **GraphQL Storefront API token**.

> **Info**
>
> The credentials you generate in this lab will be needed for future labs, so make sure you store them securely.

### Prerequisites

* A BigCommerce [sandbox store](/developer/docs/overview/sandboxes) or [trial store](https://www.bigcommerce.com/essentials/), or a full production store, with an available slot for a new storefront channel
* [Postman](https://www.postman.com/) or a similar API client

### In this lab, you will:

* Practice generating store-level v2/v3 API credentials
* Create a headless storefront channel
* Practice generating a GraphQL storefront token with Postman
* Generate and store the credentials you will use in subsequent labs

## Enable Multi-Storefront

If you are using a BigCommerce store for which you've already created a Catalyst channel in Introduction to Catalyst, you will need to ensure that Multi-Storefront is enabled in order to create the additional channel in this exercise.

1. In your BigCommerce store control panel, **navigate** to Channel Manager.
2. **Click** the "Create channel" button.
3. If you don't already have the ability to create new storefront slots, an "Enable storefront seats" button will appear in the Storefronts section. **Click** this button.

You will be presented with a prompt to confirm or update to the various requirements for Multi-Storefront.

![Image](/_fern-files/bigcommerce.docs.buildwithfern.com/826337449b63fcd15bdec7d882732fd7029455eeec371594d11db2ed05090be4/assets/learn/composable-core/multi-storefront-verifications.png)

4. **Confirm** or **update** each item in the requirements list.
5. **Exit** the channel creation process. (You won't be creating a storefront channel via the control panel.)

## **Create a Store-Level API Account**

1. In your BigCommerce store control panel, under Settings, navigate to "Store-level API accounts" and **create** a new "V3/V3 API token" account with the following scopes.

| Scope                 | Permission |
| --------------------- | ---------- |
| Customers login       | login      |
| Products              | modify     |
| Carts                 | modify     |
| Sites & routes        | modify     |
| Channel settings      | modify     |
| Storefront API tokens | manage     |

> **Info**
>
> The OAuth scopes we've set will be used both for storefront operations and management of store data. This is convenient for a development-only context, but when configuring API accounts for a real store, you should restrict the scopes available to your front-end application. Create one account with the "Customers login" and "Carts" scopes, and a separate account for management.

After saving your API account, you will be presented with three values in a modal:

* Client ID
* Client Secret
* Access token

These values will not be retrievable once the displayed modal is closed!

2. Securely **store** the access token for your API account. Optionally, you may also store the client ID and client secret.

> **Info**
>
> The following steps will involve using a Postman environment to store your access token for API requests. While you are unlikely to use the client ID and client secret within Postman, such environment variables can be a convenient central place to secure all related credentials. Since we'll be using Postman in future labs, feel free to store your credentials there now. (Make sure the environment you create is not in a shared workspace!)

## **Create a Headless Storefront Channel**

While you will use the default storefront of your BigCommerce store for redirected checkout in subsequent labs, we're going to create a separate, dedicated channel for your headless storefront itself.

1. **Create** a new Postman environment with the following variables.

| Variable Name | Value                                                  |
| ------------- | ------------------------------------------------------ |
| `v3_token`    | The access token of your store-level V2/V3 API account |
| `store_hash`  | Your store hash                                        |

2. **Create** a Postman collection and give it an appropriate name, such as "BC Composable Storefronts Intermediate."
3. **Create** a new "Create Headless Channel" HTTP request and save it to your collection. This request requires the following details.

| Field         | Value                                                                                                                                                                                                                                                                          |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Method        | POST                                                                                                                                                                                                                                                                           |
| URL           | `https://api.bigcommerce.com/stores/{{store_hash}}/v3/channels`                                                                                                                                                                                                                |
| Authorization | Set Type to "No Auth" in the Authorization tab. This will future-proof this request against any future scenario in which you've configured a specific authorization type on your collection that applies to other requests - for example, a bearer token for GraphQL requests. |

4. In the Headers tab, use the Presets drop-down to **Manage Presets**, then **add** a header preset with the following values, saving it with a name like "BC REST."

| Field        | Value            |
| ------------ | ---------------- |
| Accept       | application/json |
| Content-Type | application/json |
| X-Auth-Token | `{{v3_token}}`   |

> **Info**
>
> Make sure to enter "`{{store_hash}}` and `{{v3_token}}` exactly as they appear. These are references to the environment variables you created and will inject their values.

5. **Select** your newly created header preset to populate headers.
6. In the Body tab, **select** "raw" as the body type and "JSON" from the list of formats. **Enter** the following body, replacing `name` with a storefront name of your choice.

```json showLineNumbers={false}
{
    "name": "My Headless Storefront",
    "type": "storefront",
    "platform": "next",
    "status": "active",
    "is_visible": true,
    "is_listable_from_ui": true
}
```

Do *not* send the request just yet, as we will first add tests and logic to store the ID of the new channel.

7. In the Script tab, **enter** the following "Post-response" value:

```js showLineNumbers={false}
pm.test("Response is not an error", () => {
    pm.response.to.not.be.error;
    pm.response.to.not.have.jsonBody("errors");
});
pm.test("Response is JSON with data", () => {
    pm.response.to.have.jsonBody("data");
});
pm.test("Response includes a channel ID", () => {
    pm.expect(pm.response.json().data?.id).to.be.a("number");
});
```

These tests will ensure that the channel has been successfully created by examining the response for the channel ID.

8. **Add** the following after the previous code in the Scripts tab.

```java showLineNumbers={false}
pm.environment.unset("storefront_channel_id");
pm.environment.set("storefront_channel_id", pm.response.json().data?.id);
```

This will store the ID of the new channel permanently in an environment variable alongside your other configuration details.

9. **Save** the request, make sure you have selected your BigCommerce environment in the environment drop-down, then **send** the request and observe the results.
10. **Send** the request and verify that the tests pass in the "Test Results" tab of the response panel.
11. **Verify** that the `storefront_channel_id` variable is populated in your environment variables list.

> **Info**
>
> If your request succeeded but any issue with your Tests scripts caused `storefront_channel_id` not to be stored, you can either delete the channel in Channel Manager in your BigCommerce control panel and try the request again after correcting the issue (which will require a different channel name), or else use the [Get All Channels](/developer/api-reference/rest/admin/management/channels) API endpoint to retrieve the new channel's information and save `storefront_channel_id` manually.

## Verify Your Channel Site

1. **Create** a new HTTP request and **save** it in your collection with the name "Get Channel Site."
2. **Set** the same configuration that was used for the previous request for Authorization and Headers (using your previously created preset).
3. **Set** the request method as "GET."
4. **Set** the following as the URL of the request:

```http showLineNumbers={false}
https://api.bigcommerce.com/stores/{{store_hash}}/v3/channels/{{storefront_channel_id}}/site
```

5. **Send** the request and observe the response. **Verify** that your channel contains a "canonical" URL value with the pattern `https://store-{hash}-{channel ID}.mybigcommerce.com`. This is the URL that will be used for GraphQL Storefront API requests.
6. **Observe** the `checkout` URL in the response, which should be set to the URL of your default BigCommerce storefront. This is the configuration you'll keep for your Redirected Checkout flow in your dev environment.

> **Info**
>
> It's not actually the recommended practice to redirect to the default storefront for checkout. The checkout URL should be a domain that is assigned directly to the headless storefront channel. For the purposes of development in these lab exercises, however, you do not have a real domain to set.

Your channel does not yet have a "primary" URL, and while working with the channel in a local development environment, you will not have a public domain to set. The main implication of this will be that BigCommerce will not know how to properly generate links to your local headless storefront in your control panel or in Stencil pages like checkout.

In a full build, once you have a public domain and a strategy for checkout domain, you can update these with the following API endpoints:

* Update a Channel Site
* Upsert a Site's Checkout URL

## Create a Private Token

Your storefront application's primary interactions with BigCommerce will use the GraphQL Storefront API. For server-to-server use (including the Next.js app in the next lab), you need a **Private Token**. Create your Private Token now and store it in `private_storefront_token`.

> **Info**
>
> Private Tokens are a new token type designed specifically for server-to-server use. They are the recommended approach for headless storefronts and server-side integrations.

1. **Create** a new "Create Private Token" HTTP request and save it to your collection.
2. **Set** the same configuration that was used for the previous Create a Channel request, including the HTTP method, Authorization, Headers (using your previously created preset), and Body type.
3. **Set** the request URL to:

```http showLineNumbers={false}
https://api.bigcommerce.com/stores/{{store_hash}}/v3/storefront/api-token-private
```

4. **Enter** the following body:

```json showLineNumbers={false}
{
  "channel_id": {{storefront_channel_id}},
  "expires_at": 2147483647,
  "scopes": [
    "Unauthenticated",
    "Customer"
  ]
}
```

> **Info**
>
> Remember that you can also use a dynamic value for `expires_at`, by including a Pre-request Script to calculate a timestamp and store it as an environment or collection variable.

5. In the Scripts tab, **add** the following "post-response" value.

```js showLineNumbers={false}
pm.test("Response is not an error", () => {
    pm.response.to.not.be.error;
    pm.response.to.not.have.jsonBody("errors");
});
pm.test("Response is JSON with data", () => {
    pm.response.to.have.jsonBody("data");
});
pm.test("Response includes token", () => {
    pm.expect(pm.response.json().data?.token).to.be.a('string');
});

const token = pm.response.json().data?.token;
if (token) {
    pm.environment.unset("private_storefront_token");
    pm.environment.set("private_storefront_token", token);
}
```

6. **Send** the request and verify that the tests pass in the "Test Results" tab of the response panel.
7. **Verify** that the `private_storefront_token` variable is populated in your environment variables list. You will use this token (as `BIGCOMMERCE_STOREFRONT_TOKEN`) in the Next.js app in the next lab.

## Assign Catalog Data

Remember that existing catalog data in your store, if it exists, will not automatically be associated with your new channel. You must create a unique category tree for the channel and assign products.

1. **Log into** your BigCommerce store control panel.
2. In Products > Product Categories, **create a category tree** for your new channel.

![Image](/_fern-files/bigcommerce.docs.buildwithfern.com/e1fa24e771114be50ea9a3ebe58747dd04b00619e26d402bef733500e2f3e2bc/assets/learn/composable-core/category-tree-create.png)

3. **Create** two or more top-level categories, making sure to **assign** them to the appropriate channel.
4. If you have existing products in your store that you want to use on your headless channel, **visit** Products > View and **check** the checkboxes next to all products you want to assign.
5. Use the bulk actions at the top of the product list to **Add to Channels**. Select your headless channel and **Add**.
6. **Add** your products to categories within your headless channel's category tree. You can use the **Add to Categories** bulk action as appropriate, for each group of products you wish to add to a particular category.

If you prefer to create new products for use in your headless channel, subsequent labs will outline the necessary fields you will want to include for the features you'll be building.

## Configure Shipping and Payments

If you want to be able to complete checkout on your Catalyst storefront, you'll need to make sure you have the appropriate minimal store configuration in place for shipping and payments.

This step is not channel-specific, so if you've previously configured shipping and payment options for your store, you won't need to do any additional setup.

We won't walk through the details of configuring your store settings, but make sure you have:

* A Shipping Zone that applies to any billing address you will use at checkout
* An enabled Shipping Method on the Shipping Zone
* An enabled test/sandbox Payment Method. (Check the "Enable test credit card payments" option in your Payments Methods settings for the simplest option.)

## Resources

* [Postman Overview](https://learning.postman.com/docs/introduction/overview/)
* [Store-Level API Accounts](/developer/docs/overview/api-fundamentals/api-accounts#store-level-api-accounts)
* [Get All Channels](/developer/api-reference/rest/admin/management/channels)
* [Update a Channel Site](/developer/api-reference/rest/admin/management/channels/site/update-channel-site)
* [Upsert a Site's Checkout URL](/developer/api-reference/rest/admin/management/channels/site-checkout-url/update-checkout-url)
* [Shipping Zones](https://support.bigcommerce.com/s/article/Shipping-Zones)
* [Shipping Methods](https://support.bigcommerce.com/s/article/Shipping-Methods)