> 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 - Authentication and Postman Setup

Plan: Developer Foundations

Lesson 9 of 28 · 30 min

## Prerequisites

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

## In this lab, you will:

* Generate a store-level v2/v3 API token
* Create a **Storefront token** (with CORS) for browser/client use → stored in `storefront_token`
* Create a **Private Token** for server-to-server use → stored in `private_storefront_token`
* View the GraphQL Storefront API example with your own store's data

## Create a Store-level API Account

1. **Log in** to your BigCommerce store.
2. **Navigate** to *Settings > Store-level API Accounts.*
3. **Click** the Create API Account button.
4. **Choose** "V2/V3 API token" as the token type.
5. **Type** a name for the API Account.
6. **Configure** OAuth scopes as follows (some of these scopes are for later labs).

| Scope                                        | Permission |
| -------------------------------------------- | ---------- |
| Create payments                              | create     |
| Get payment methods                          | read-only  |
| Storefront API Tokens                        | manage     |
| Storefront API Customer Impersonation Tokens | manage     |

7. **Click** the Save button.
8. **Copy** the Access Token and save the API account information in a place you can access later.

## Create a Storefront Token (browser/client use)

You'll create a **Storefront token** with `allowed_cors_origins` so it can be used from a browser (e.g. for the "View Example" step later). This token is stored in `storefront_token`. These instructions assume Postman.

### Step 1: Configure an Environment

1. **Record** the store hash for your BigCommerce store. You can find this in the URL of your control panel, which is in the format `https://store-{store hash}.mybigcommerce.com`.
2. In Postman, **create** a new environment and give it a name.
3. **Create** the following environment variables.

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

### Step 2: Configure the Storefront Token Request

1. **Create** a Postman collection and give it an appropriate name, such as "BC GraphQL Storefront API."
2. **Create** a new HTTP request, then **Save** it in your new collection with the name "REST Create Storefront Token (with origin)."
3. In the Authorization tab, **set** Type to "No Auth." We will eventually configure GraphQL style authentication on the collection, and this ensures that this authentication will not be used for this REST request.
4. **Set** "POST" as the request method.
5. **Enter** the following exact value as the URL for your request:

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

6. In the Headers tab, use the Presets drop-down to **Manage Presets**, then **Add** a header preset (for REST) with the following values:

| Field        | Value            |
| ------------ | ---------------- |
| Accept       | application/json |
| Content-Type | application/json |
| X-Auth-Token | \{\{v3\_token}}  |

7. **Select** your newly created header preset to populate headers.
8. In the Body tab, **select** "raw" as the body type, then **select** "JSON" in the drop-down list. Enter the following body.

```json showLineNumbers={false}
{
  "allowed_cors_origins": [
    "https://bigcommerce.github.io"
  ],
  "channel_id": {{storefront_channel_id}},
  "expires_at": 2147483647
}
```

> **Info**
>
> The `expires_at` value used here is simply the maximum allowed expiration date/time. Customer impersonation tokens can be long-lived, but for production tokens you will likely use a more controlled expiration time and rotate the token periodically. In Postman, try using a Pre-request Script to dynamically calculate an appropriate expiration time and set it as a collection variable.
>
> ```js showLineNumbers={false}
> const dt = new Date();
> dt.setMonth(dt.getMonth() + 3);
> const gqlExpireTime = Math.floor(dt.valueOf() / 1000);
> pm.collectionVariables.set("storefront_token_expire", gqlExpireTime);
> ```

You should test your request now (make sure to select your environment in the environments drop-down) and verify that a token is successfully received.

### Step 3: Add Tests

1. In the Scripts tab of your "REST Create Storefront Token (with origin)" request, **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');
});
```

This will run tests whenever the request is sent, verifying that the response is not an error and contains a token in the body.

2. Make sure your environment is selected in the environments drop-down, **send** the request, and **verify** that the tests pass in the "Test Results" tab of the response panel.

## Create a Private Token

For server-to-server GraphQL requests (and the rest of this course), use a **Private Token**. Create a new request like the Storefront token one above, with these differences so the token is stored in `private_storefront_token`:

### Step 1: Configure the Private Token Request

1. **Save** the request with the name "REST Create Private Token (server-to-server)."
2. **Set** the request URL to:
   ```http showLineNumbers={false}
   https://api.bigcommerce.com/stores/{{store_hash}}/v3/storefront/api-token-private
   ```
3. **Enter** a body with `channel_id`, `expires_at`, and `scopes` (required):

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

You should test your request now (make sure to select your environment in the environments drop-down) and verify that a token is successfully received. In our next steps, however, we'll tweak the request to store the token permanently.

### Step 2: Store the Private Token

You've now got a reliable Postman request for generating a new GraphQL token at any time. Rather than manually copy/pasting the token to store it for later use, we can expand the configuration of the request to automatically store the value in our Postman environment variables, right alongside the other credentials we've saved. This approach will also make it simple to utilize the token in any other GraphQL Storefront requests you may want to prototype in Postman.

While we're at it, we'll also include appropriate tests to verify the response.

1. In the Scripts tab of your "REST Create Private Token (server-to-server)" request, **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');
});
```

2. Make sure your environment is selected in the environments drop-down, **send** the request, and verify that the tests pass in the "Test Results" tab of the response panel.
3. Back in the Scripts tab, **add** the following code after the tests.

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

4. **Send** the request again.

If you view your Postman environment, you should now see a `private_storefront_token` variable in addition to the `v3_token` and other values you've stored!

### Step 3: Configure GraphQL Authorization on the Collection

1. **Open** your "BC GraphQL Storefront API" collection.
2. In the Authorization tab, **set** Type to "Bearer Token."
3. **Enter** the following as the value for Token (this uses the Private Token for server-to-server GraphQL requests):

```text showLineNumbers={false}
{{private_storefront_token}}
```

4. **Save** the collection.

You've now configured your collection to automatically use the most recently generated token for any GraphQL requests.

## View Example With Your Store's Data

1. **Run** your "REST Create Storefront Token (with origin)" request and **copy** the token from the response.
2. **Go** to [https://bigcommerce.github.io/storefront-api-examples/html-bootstrap-vanillajs/](https://bigcommerce.github.io/storefront-api-examples/html-bootstrap-vanillajs/).
3. **Paste** your store's URL in the "Store URL" field.
4. **Paste** your token into the "Storefront API Token" field.
5. **Click** Submit.
6. **View** web page.