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 headless server-to-server use → stored in private_token
• View the GraphQL Storefront API example with your own store’s data
• Log in a customer account
• Create a Customer Impersonation Token with Postman

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.

In this lab you will create two tokens; each is stored in its own variable: Storefront token (this section) → storefront_token; Private Token (next section) → private_token.

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 and Store the Storefront Token

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');
});
const token = pm.response.json().data?.token;
if (token) {
    pm.environment.unset("storefront_token");
    pm.environment.set("storefront_token", token);
}

This stores the Storefront token in storefront_token (for browser/client use). In the next section you will create a Private Token and store it in private_token (for server-to-server requests).

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 (headless server-to-server use)

For headless 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_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",
    "B2B"
  ]
}

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_token");
    pm.environment.set("private_token", token);
}

4. Send the request again.

You should now have both storefront_token (from the previous section) and private_token in your environment. The collection is set to use private_token for GraphQL requests in the following labs.

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_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 (or use the storefront_token already in your environment) 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.

Create a Customer Impersonation Token with Postman

The GraphQL requests you’ll create throughout subsequent labs will utilize the Private Token you’ve created (private_token), but in this section you’ll also practice creating a customer impersonation token.

Follow the steps you previously used to create and store a Private Token, but with the following differences:

Step 1: Create the Request

1. Save the request with the name “REST Create Storefront CIT”.
2. Enter the following value as the URL for this request:

https://api.bigcommerce.com/stores/{{store_hash}}/v3/storefront/api-token-customer-impersonation

3. Enter a body with only channel_id and expires_at:

{
  "channel_id": {{storefront_channel_id}},
  "expires_at": 2147483647
}

4. In the Scripts for the request, add tests in the “Post-response” value and store the new token in a new environment variable: storefront_impersonation_token.

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("storefront_impersonation_token");
    pm.environment.set("storefront_impersonation_token", token);
}

5. Send the request, verify that tests are successful, and confirm that the storefront_impersonation_token variable is set on the environment.