Lab - Authentication and Postman Setup

Prerequisites

• A BigCommerce sandbox store or trial store, or a full production store
• Postman 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
• Log in a customer account

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

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.

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:

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:

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.

{
  "allowed_cors_origins": [
    "https://bigcommerce.github.io"
  ],
  "channel_id": {{storefront_channel_id}},
  "expires_at": 2147483647
}

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.

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:

   https://api.bigcommerce.com/stores/{{store_hash}}/v3/storefront/api-token-private
3. Enter a body with channel_id, expires_at, and scopes (required):

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

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.

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):

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

Log in to a Customer Account

1. Go to Settings > Storefront API Playground.
2. Copy the code below:

mutation Login($email: String!, $pass: String!) {
   login(email: $email, password: $pass) {
     customer{
      entityId
      firstName
      lastName
      customerGroupId
    }
   }
 }

3. Paste into Storefront API Playground.
4. Copy and Paste the code below into the Query Variables section in Storefront API Playground to set the variables for the request:

(Note: replace {password} and {emailAddress} with the password and email address of a customer account in the store)

{"pass":"{password}", "email":"{emailAddress}"}

5. Run the request.
6. Observe response and customer logged in.