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.

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

• clicking Install in the App Marketplace, or
• following a direct installation link.

2. 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.
3. 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.
4. The app sends POST request to BigCommerce to request a unique access_token for the store.
5. BigCommerce responds with either an error or an access_token unique to the merchant’s store; see receiving the access_token response.
6. The app saves the store’s unique access_token and handles any internal logic.
7. 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

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.

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

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.

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

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.

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

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) 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). For a list of the top web application security risks and best practices for avoiding them, see OWASP Top Ten (owasp.org).

Helpful tools

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

• Python API Client
  • Fetches access_token
  • Verifies signed_payload_jwt
• Node API Client
  • Fetches access_token
  • Verifies signed_payload_jwt
• PHP API Client
  • Fetches access_token
• Ruby OmniAuth Gem
  • Fetches access_token

Next step

• Handle load, uninstall, and remove_user callbacks

Resources

Related articles

• About Our APIs
• Authentication

Sample apps

• Node / React / Next.js with quick start tutorial
• Python / Flask
• PHP / Silex
• Ruby / Sinatra
• Laravel / React

Tools

• Node API Client
• Python API Client
• PHP API Client
• Ruby API Client
• Ruby OmniAuth Gem
• BigDesign Developer Playground
• Figma Component Library

Blog posts

• How to Test App Authentication Locally with ngrok
• Building a BigCommerce App Using Laravel and React
• BigDesign Tutorial

Additional resources

• OAuth 2.0 Simplified (oauth.net)
• RFC 6749 (tools.ietf.org)
• OWASP Top Ten (owasp.org)