Skip to content

Commit

Permalink
Merge branch 'main' into DEVDOCS-5596
Browse files Browse the repository at this point in the history
  • Loading branch information
bc-traciporter authored Dec 14, 2023
2 parents ac94878 + 99d3464 commit c8c6d4e
Show file tree
Hide file tree
Showing 8 changed files with 25 additions and 17 deletions.
16 changes: 12 additions & 4 deletions docs/api-docs/apps/guide/apps-05-oauth.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ It may be more appropriate for your application to use an API client to handle t

<Callout type="info">
#### Store owner access_token constraint
Typically, only [store owners](https://support.bigcommerce.com/s/article/Store-API-Accounts#creating) can create API accounts and `access_token`s for a store. However, when an app is approved to be publicly available for additional stores to install, it can generate `access_token`s *on behalf* of store owners.
Typically, only [store owners](https://support.bigcommerce.com/s/article/Store-API-Accounts#creating) and authorized users can create API accounts and `access_token`s for a store. However, when an app is approved to be publicly available for additional stores to install, it can generate `access_token`s *on behalf* of store owners.
</Callout>

## Overview
Expand Down Expand Up @@ -123,6 +123,11 @@ BigCommerce responds to the access_token request with JSON that contains a perma
"username": "[email protected]",
"email": "[email protected]"
},
"owner": {
"id": 12345,
"username": "[email protected]",
"email": "[email protected]"
},
"context": "stores/g5cd38",
"account_uuid": "12345678-90ab-cdef-1234-567890abcdef"
}
Expand All @@ -134,9 +139,12 @@ BigCommerce responds to the access_token request with JSON that contains a perma
|:---------|:-----|:------------|
| `access_token` | string | The semi-permanent security token that your app can use to make requests on behalf of the store. Save this value securely for future requests. |
| `scope` | string | A space-separated list of the OAuth scopes this `access_token` authorizes access to. |
| `user.id` | integer | BigCommerce’s unique identifier for the merchant or authorized user. Save this value to identify the user in future requests. |
| `user.username` | string | The username that the initiating user has on file with BigCommerce. |
| `user.email` | string | The email address that the owner or authorized user has on file with BigCommerce. Save this value for future requests. |
| `user.id` | integer | BigCommerce’s unique identifier for the authorized user. Save this value to identify the user in future requests. |
| `user.username` | string | The username that the authorized user has on file with BigCommerce. |
| `user.email` | string | The email address that the authorized user has on file with BigCommerce. Save this value for future requests. |
| `owner.id` | integer | BigCommerce’s unique identifier for the store owner. Save this value to identify the user in future requests. |
| `owner.username` | string | The username that the store owner has on file with BigCommerce. |
| `owner.email` | string | The email address that the store owner has on file with BigCommerce. Save this value for future requests. |
| `context` | string | The path that identifies the store in API requests to `https://api.bigcommerce.com{:http}`; a string of the form `stores/{STORE_HASH}`. |
| `account_uuid` | string, UUID | The ID of the Developer Portal account that registered the app profile. |

Expand Down
10 changes: 5 additions & 5 deletions docs/api-docs/apps/guide/apps-06-callbacks.mdx
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Single-Click App Callback Handlers

After a store owner installs your single-click app, they and their authorized users will need to use it and configure any settings. In turn, your app will likely need to store and manage information about the stores and users you're supporting.
After a store owner or authorized user installs your single-click app, they and other authorized users will need to use it and configure any settings. In turn, your app will likely need to store and manage information about the stores and users you're supporting.

This article is a reference for endpoints to which we send event-driven callbacks, and a guide to writing handlers that verify and use our JWT payloads. It also describes the payload schema of the `signed_payload_jwt`.

Expand All @@ -21,12 +21,12 @@ The following table lists the app management callbacks that BigCommerce stores s
|:---------|:--------:|:---------------|:--------|:-----------------|:------------------|
| `GET /auth{:http}` | yes | browser | URL-encoded | markup | See [Implement the OAuth flow](/docs/integrations/apps/guide/auth). |
| `GET /load{:http}` | yes | browser | JWT | markup | The store owner or authorized user clicks to load the app. |
| `GET /uninstall{:http}` | no | server | JWT | JSON | The store owner clicks to uninstall the app. |
| `GET /uninstall{:http}` | no | server | JWT | JSON | The store owner or authorized user clicks to uninstall the app. |
| `GET /remove_user{:http}` | no | server | JWT | JSON | The store owner revokes a user's access to the app. |

## Render the app with load

Once the store owner installs your app, it appears on the **Apps** sub-menu list in their store control panel, as well as their authorized users' control panels. When a user clicks your app's listing or another referring UI component, BigCommerce dispatches a request to your app's `GET /load{:http}` endpoint. The following is an example request:
Once the store owner or authorized user installs your app, it appears on the **Apps** sub-menu list in their store control panel, as well as their authorized users' control panels. When a user clicks your app's listing or another referring UI component, BigCommerce dispatches a request to your app's `GET /load{:http}` endpoint. The following is an example request:

```http filename="Example request: /load callback from BigCommerce"
GET https://your_app.example.com/load?signed_payload_jwt={header_b64.payload_claims_b64.signature_b64}
Expand All @@ -37,7 +37,7 @@ After your app [verifies the payload](#decode-and-verify-signed_payload_jwt), [i

## Deactivate stores with uninstall

When the store owner clicks the **Uninstall** button on your app's card in the store control panel, BigCommerce dispatches a request to the app's `GET /uninstall{:http}` endpoint. The following is an example request:
When the store owner or authorized user clicks the **Uninstall** button on your app's card in the store control panel, BigCommerce dispatches a request to the app's `GET /uninstall{:http}` endpoint. The following is an example request:

```http filename="Example request: uninstall callback from BigCommerce"
GET https://your_app.example.com/uninstall?signed_payload_jwt={header_b64.payload_claims_b64.signature_b64}
Expand Down Expand Up @@ -74,7 +74,7 @@ Use the payload claim data to identify the store and user. What your app should
| Endpoint | Multiple Users Enabled | Multiple Users Not Enabled |
|:---------|:-----------------------|:---------------------------|
| `GET /load{:http}` | Compare user to store owner or existing user; if no match, it's a new user; add them to the app's database. | Matches store owner |
| `GET /uninstall{:http}` | Compare user to store owner or existing user; only store owner can uninstall an app. | Matches store owner |
| `GET /uninstall{:http}` | Compare user to store owner or existing user; only store owner or authorized users can uninstall an app. | Matches store owner |
| `GET /remove_user{:http}` | Compare user to users stored in app database; remove matching user from database. | N/A |


Expand Down
4 changes: 2 additions & 2 deletions docs/api-docs/apps/guide/apps-07-users.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -22,8 +22,8 @@ Use your draft app and your sandbox store to review this behavior.

Apps with **Multiple Users** enabled can expect the `email` and `ID` of the user that initiated the callback in addition to the owner's `email` and `ID` in the JSON object sent in the `load` request. If a `load` request is sent with information for a user you haven't seen, provision the user account and associate it with the store in your database.

Because you know the store owner's `email` and `ID` from the app installation sequence, your app can distinguish store owners from other users. This allows you to provide different user experiences based on the information in the load request. Here is a summary of the two types of users:
- **Store owner**: Can `install`, `uninstall`, and `load` apps.
Because you know the store owner or user's `email` and `ID` from the app installation sequence, your app can distinguish store owners from other users. This allows you to provide different user experiences based on the information in the load request. Here is a summary of the two types of users:
- **Store owner** and **authorized users**: Can `install`, `uninstall`, and `load` apps. Store owners must grant permissions so that authorized users can install or uninstall apps.
- **Users**: Cannot `install` or `uninstall` apps. Users are permitted only to `load` the apps that a store owner authorized.

## The remove user request
Expand Down
4 changes: 2 additions & 2 deletions docs/api-docs/apps/guide/apps-13-publishing.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -50,9 +50,9 @@ Specify app type, multiple users support, callback URLs, and OAuth scopes; and,
|:-----------------------|:---------------------------------------------------------------------------|
| Multiple Users | Optionally allow your app to be accessible to store users other than owner |
| App Type | Type of app; single-click recommended |
| Auth Callback URL | Requested when `install` clicked |
| Auth Callback URL | Requested when store owner or authorized user clicks `install` |
| Load Callback URL | Requested when user launches app |
| Uninstall Callback URL | Requested when store owner clicks uninstall |
| Uninstall Callback URL | Requested when store owner or authorized user clicks `uninstall` |
| OAuth Scopes | OAuth scopes the app requires |
| Test Instructions | Instructions needed to test the app thoroughly |

Expand Down
2 changes: 1 addition & 1 deletion docs/api-docs/getting-started/api-status-codes.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -71,7 +71,7 @@ This article covers [REST](#rest-api-http-status-codes) and [GraphQL](#graphql-a
|**400**|Invalid syntax, required data missing, `content-type` header missing|Double-check request body for syntax errors and missing data; check `content-type` header.|
|**401** |API credentials are missing or invalid.|Double-check the `access_token` and `client_id`.|
|||Send cURL request with the same credentials to rule app or config issues.|
|**403**| App lacks required OAuth scopes, a store-owner account changed, operations resulting from API request exceed a platform limit, or URL requested is incorrect.|Double-check OAuth Scopes in **control panel** > **API Accounts** or in **Developer Portal** > **My Apps**.|
|**403**| App lacks required OAuth scopes, a store-owner account changed, operations resulting from API request exceed a platform limit, or URL requested is incorrect. User does not have app install or uninstall permissions. |Double-check OAuth Scopes in **control panel** > **API Accounts** or in **Developer Portal** > **My Apps**.|
|||Check the URL. Are the endpoint and store hash correct?|
|||Ensure [platform limits](https://support.bigcommerce.com/s/article/Platform-Limits#product-catalog-limits) have not been reached.|
|**415**| Request headers specify an unsupported `content-type` (or header is missing).|Double-check `content-type` request header.|
Expand Down
2 changes: 1 addition & 1 deletion docs/api-docs/getting-started/rest-api-authentication.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -61,7 +61,7 @@ To delete a store-level API account, consult our Knowledge Base article on [Dele

## App-level API accounts

You can [create app-level API accounts](#creating-app-level-api-credentials) in the [Developer Portal](https://devtools.bigcommerce.com). After a store owner installs and authorizes an app, most apps use access tokens generated from the API account's client ID, client secret, and a temporary grant code to read and change store data. [Generate access tokens](#app-level-access-tokens) with the BigCommerce-initiated grant code authorization flow.
You can [create app-level API accounts](#creating-app-level-api-credentials) in the [Developer Portal](https://devtools.bigcommerce.com). After a store owner or authorized user installs and authorizes an app, most apps use access tokens generated from the API account's client ID, client secret, and a temporary grant code to read and change store data. [Generate access tokens](#app-level-access-tokens) with the BigCommerce-initiated grant code authorization flow.

Some APIs use app-level API accounts to implement alternative authentication patterns. For a summary of all our authentication methods, see [Authentication and Example Requests](/docs/start/authentication).

Expand Down
2 changes: 1 addition & 1 deletion docs/api-docs/partner/becoming-a-partner.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -48,7 +48,7 @@ Once approved, you will receive one or more emails listing your partner credenti

BigCommerce offers training modules to help you get up to speed with the BigCommerce platform. You will need to complete these training modules to become a BigCommerce Certified Partner.

To access the training modules, log into the [Partner Portal](https://partners.bigcommerce.com/), hover over the **Training** tab (top navigation), and select **eLearning Modules**. This path will take you to the [Training & Enablement](https://partners.bigcommerce.com/English/Solutions/training/training_and_enablement.aspx) page.
To access the training modules, log into the [Partner Portal](https://partners.bigcommerce.com/), hover over the **Education** tab (top navigation), and select **Training & Certification**. This path will take you to the [Trainings](https://partners.bigcommerce.com/English/Solutions/training/training_and_enablement.aspx) page.

<Callout type="info">
#### Certifications and the BigDev Bootcamp
Expand Down
2 changes: 1 addition & 1 deletion docs/api-docs/partner/subscriptions/foundation-guide.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -97,7 +97,7 @@ During development, you'll work with two Stripe accounts. You'll create them bot

<Callout type="info">
#### Multi-tenant setup
Prior to installing the app, add the merchant account to the sandbox store as a payment method. When the app is installed, the UI prompts the store owner to give the app permission to make charges on behalf of the store. Upon consent, the app initiates an OAuth code grant flow to link the merchant's Stripe account with the app's Stripe Connect-enabled account. The diagram below shows the configuration and the integration process.
Prior to installing the app, add the merchant account to the sandbox store as a payment method. When the app is installed, the UI prompts the store owner or authorized user to give the app permission to make charges on behalf of the store. Upon consent, the app initiates an OAuth code grant flow to link the merchant's Stripe account with the app's Stripe Connect-enabled account. The diagram below shows the configuration and the integration process.
</Callout>

![platform-configuration](https://storage.googleapis.com/bigcommerce-production-dev-center/images/platform-configuration.png "Multi-Tenant Stripe Platform Configuration")
Expand Down

0 comments on commit c8c6d4e

Please sign in to comment.