BigCommerce
Integrations
Apps
Guide
Implementing OAuth

Single-Click App OAuth Flow

After you install your draft app and create an app profile, you're ready to write the code grant authorization flow that generates a unique access_token for each store that installs your app. This article covers the sequence and contents of API requests and responses in the code grant authorization flow for a BigCommerce app.

It may be more appropriate for your application to use an API client to handle this logic; see the list of BigCommerce API clients that expose OAuth-related helper methods.

Store owner access_token constraint

Typically, only store owners (opens in a new tab) and authorized users can create API accounts and access_tokens for a store. However, when an app is approved to be publicly available for additional stores to install, it can generate access_tokens on behalf of store owners.

Overview

Your app must expose a callback endpoint, GET /auth, that the merchant's store control panel can hit to initiate the code grant authorization flow. For a list of all the callback endpoints your app can expose, both required and optional, see Single-Click App Callback Handlers.

BigCommerce uses a modified version of the OAuth2 authorization code grant (tools.ietf.org) (opens in a new tab). The sequence is as follows:

  1. The merchant initiates installing your app by signing in to their store control panel and doing one of the following:
  1. The merchant accepts the app's OAuth scope permissions. The OAuth consent view presented to the merchant requires them to approve all the scopes to install the app; at this time, merchants cannot pick and choose scopes.
  2. The merchant's browser sends a GET request to the app server's GET /auth endpoint that contains some of the information necessary to request a unique access_token for the store.
  3. The app sends POST request to BigCommerce to request a unique access_token for the store.
  4. BigCommerce responds with either an error or an access_token unique to the merchant's store; see receiving the access_token response.
  5. The app saves the store's unique access_token and handles any internal logic.
  6. The app sends a response to the browser's GET request in step 3 that contains markup to render the app's landing view in the iFrame the store control panel provides.

After your app has an access_token for the store, the following events can mark the access_token for invalidation the next time the merchant opens the app:

  • You change the app's OAuth scopes.
  • The merchant's email address changes.

The next time the merchant opens the app in the store control panel, the browser will prompt them to accept the changes. Once they accept, their previous access_token will be invalid, and your app will receive a fresh auth callback for their store.

Receiving the auth callback

Auth callback URL requirement

In production, all app callback URLs must be publicly available, fully qualified, and served over TLS/SSL.

The request to your app's GET /auth endpoint contains query parameters required to request an access_token.

It's a best practice to request and receive an access_token before responding to the auth callback.

Example request: auth callback
GET https://your_app.example.com/auth?account_uuid=12345678-90ab-cdef-1234-567890abcdef&code=qr6h3thvbvag2ffq&context=stores%2Fg5cd38&scope=store_v2_orders+store_channel_listings_read_only
Accept: text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3;q=0.9
Referer: https://login.bigcommerce.com/

Query parameters in auth callback

ParameterDescription
codeThe proverbial code in the code grant authorization flow; exchange for a semi-permanent access_token.
scopeA space-separated list of the OAuth scopes associated with this app's API account.
contextThe path that identifies the store in API requests to https://api.bigcommerce.com; a string of the form stores/{STORE_HASH}.
account_uuidThe ID of the Developer Portal account that registered the app profile.

Before proceeding with the grant code authorization flow, it's a best practice to validate the list of scopes to ensure that it matches the scopes currently configured in your app profile.

Requesting the access_token

To generate an access_token for the merchant's store, send a POST request to https://login.bigcommerce.com/oauth2/token. The request body contains a combination of query arguments from the auth callback and credentials from your app profile.

Example request: Create an access_token
POST https://login.bigcommerce.com/oauth2/token
Accept: application/json
Content-Type: application/json
 
{
  "client_id": {CLIENT_ID},
  "client_secret": {CLIENT_SECRET},
  "code": "qr6h3thvbvag2ffq",
  "context": "stores/g5cd38",
  "scope": "store_v2_orders store_channel_listings_read_only",
  "grant_type": "authorization_code",
  "redirect_uri": "https://your_app.example.com/auth"
}

Request body properties in the access_token request

PropertyDescription
client_idYour app's client ID.
client_secretYour app's client secret.
codeThe code from the auth callback; see the list of auth callback query parameters.
scopeThe scope list from the auth callback; see the list of auth callback query parameters.
contextThe store context from the auth callback; see the list of auth callback query parameters.
grant_typeThe value is always authorization_code.
redirect_uriIdentical to the auth callback registered in the app profile.

Receiving the access_token response

BigCommerce responds to the access_token request with JSON that contains a permanent access_token, among other information. Use this access_token to authenticate API requests the app makes on behalf of the store; see Authentication and Example Requests. To provide the most responsive app architecture and re-authentication checks, save all the response values.

Example response: Create an access_token
{
  "access_token": "xxxxalphanumstringxxxx",
  "scope": "store_v2_orders store_channel_listings_read_only",
  "user": {
    "id": 24654,
    "username": "merchant@example.com",
    "email": "merchant@example.com"
  },
  "owner": {
    "id": 12345,
    "username": "owner@example.com",
    "email": "owner@example.com"
  },
  "context": "stores/g5cd38",
  "account_uuid": "12345678-90ab-cdef-1234-567890abcdef"
}

Response body properties for the access_token request

PropertyTypeDescription
access_tokenstringThe semi-permanent security token that your app can use to make requests on behalf of the store. Save this value securely for future requests.
scopestringA space-separated list of the OAuth scopes this access_token authorizes access to.
user.idintegerBigCommerce’s unique identifier for the authorized user. Save this value to identify the user in future requests.
user.usernamestringThe username that the authorized user has on file with BigCommerce.
user.emailstringThe email address that the authorized user has on file with BigCommerce. Save this value for future requests.
owner.idintegerBigCommerce’s unique identifier for the store owner. Save this value to identify the user in future requests.
owner.usernamestringThe username that the store owner has on file with BigCommerce.
owner.emailstringThe email address that the store owner has on file with BigCommerce. Save this value for future requests.
contextstringThe path that identifies the store in API requests to https://api.bigcommerce.com; a string of the form stores/{STORE_HASH}.
account_uuidstring, UUIDThe ID of the Developer Portal account that registered the app profile.

Responding to the auth callback

After you save the access_token response body information, respond to the GET /auth callback with markup and assets to render in the store control panel. BigCommerce renders the response view inside an iFrame, so ensure that any JavaScript you send is scoped to avoid conflicts with the store control panel's JavaScript.

If you do not respond, the merchant will be left looking at a blank screen and will not be able to interact with your app.

Security considerations

RFC 6749 (tools.ietf.org) (opens in a new tab) discusses security considerations, recommendations, and requirements. The following are some requirements and recommendations applicable to apps:

  • Request access tokens with the minimal scope necessary.
  • Keep access tokens and client secrets confidential in transit and storage.
  • Educate end-users about the risks phishing attacks pose.
  • Implement CSRF protection on redirect URIs.

For additional details, see Security Considerations in RFC 6749 (tools.ietf.org) (opens in a new tab). For a list of the top web application security risks and best practices for avoiding them, see OWASP Top Ten (owasp.org) (opens in a new tab).

Helpful tools

The following BigCommerce API clients expose helper methods for BigCommerce's code grant authorization flow:

Next step

Resources

Related articles

Sample apps

Tools

Blog posts

Additional resources

Did you find what you were looking for?
Locating app IDsHandling callbacks