GraphQL Account API overview

Introduction

The GraphQL Account API’s users feature lets you create, edit, and delete BigCommerce control panel users. This highly requested feature is primarily useful for Enterprise merchants who need to audit existing users or integrate with third-party user management systems.

What is a user

A user is an account that can sign in to the BigCommerce control panel for an account or store. A user corresponds with one email address.

Prerequisites

Before getting started with the GraphQL Account API’s users feature, make sure you have the following:

• BigCommerce store
• A valid access token from an account-level API account that has sufficient permissions to make the desired requests.

To learn more about making requests, see the next section on Getting Started.

Rate Limits

Account based rate limiting will affect all endpoints that begin with /accounts.

The limit is set to 70 requests per hour.

Refer to our API Rate Limit Best Practices Documentation to help you manage your API usage effectively.

OAuth scopes

GraphQL schemas don’t carry per-operation OAuth scope metadata the way OpenAPI does, so individual mutation and query pages can’t render a required-scope block. Use the table below to map each operation to the scope it requires.

For more information on these OAuth scopes, see the Guide to API Accounts.

For more information on access token authentication, see Authentication and Example Requests.

Getting started

The GraphQL Account API’s users feature introduces a new way to manage control panel users. Using an OAuth-based API account, you can integrate our platform with your current system to better serve the store or account’s needs.

Begin with the following steps to get started:

1. Request an access token in the Settings > Account-level API accounts menu in the store control panel. Note that this is different from a store-level API account.
2. Use a GraphQL client such as Altair to test the API.
3. In the client, set the request URL to https://api.bigcommerce.com/accounts/{account_uuid}/graphql.
4. You can obtain the Account UUID identifier when creating the token or copy it from the API Path field.
5. Send an X-Auth-Token request header with the access token as its value.
6. Use the request body to send the GraphQL query or mutation you want to perform.

Example requests

This section contains examples of GraphQL Account API users queries and mutations that you can send with the following HTTP configuration:

POST https://api.bigcommerce.com/accounts/{{account_uuid}}/graphql
X-Auth-Token: {{access_token}}
Accept: application/json
Content-Type: application/json

Account details

The following query returns details about an account:

1
query {
2
  account {
3
    id
4
    accountInfo {
5
      name
6
    }
7
  }
8
}

Account users

The following query returns details about an account’s users. Note that a standard cursor-based pagination is supported.

1
query {
2
  account {
3
    id
4
    users {
5
      edges {
6
        node {
7
          id
8
          email
9
          firstName
10
          lastName
11
        }
12
      }
13
    }
14
  }
15
}

Account stores users

The following query returns details about the users of an account’s stores:

1
query {
2
  account {
3
    id
4
    stores {
5
      edges {
6
        node {
7
          id
8
          name
9
          storeHash
10
          users {
11
              collectionInfo {
12
                totalItems
13
              }
14
            edges {
15
              node {
16
                id
17
                email
18
                firstName
19
                lastName
20
                locale
21
                lastLoginAt
22
                permissions
23
                status
24
                updatedAt
25
                apps {
26
                  edges {
27
                    node {
28
                      id
29
                      name
30
                    }
31
                  }
32
                }
33
              }
34
            }
35
          }
36
          apps {
37
            edges {
38
              node {
39
                id
40
                name
41
              }
42
            }
43
          }
44
        }
45
      }
46
    }
47
  }
48
}

Account apps

The following query returns details about an account’s apps:

1
query {
2
  account {
3
    id
4
    apps {
5
      edges {
6
        node {
7
          id
8
          name
9
        }
10
      }
11
    }
12
  }
13
}

Add user to account

The following mutation adds a user to an account:

1
mutation {
2
  account {
3
    addUserToAccount(
4
      input: {
5
        email: "jane.doe@example.com"
6
      }
7
    ) {
8
      account {
9
        accountInfo {
10
          name
11
        }
12
      }
13
    }
14
  }
15
}

Remove user from account

The following mutation removes a user from an account:

1
mutation {
2
  account {
3
    removeUserFromAccount(
4
      input: {
5
        email: "jane.doe@example.com"
6
      }
7
    ) {
8
      accountId,
9
      userId
10
    }
11
  }
12
}

Add user to store

The following mutations add a user to a store:

Example using the user’s ID to add the user to the store, the user in this case must be part of the account:

1
mutation {
2
  user {
3
    addUserToStore(
4
      input: {
5
        user: {
6
          id: "bc/account/user/{user_id}"
7
        },
8
        storeId:"bc/account/store/{store_id}"
9
      }
10
    ) {
11
      storeId
12
    }
13
  }
14
}

Example using the user’s email to add the user to the store:

1
mutation {
2
  user {
3
    addUserToStore(
4
      input: {
5
        user: {
6
          email: "bc/account/user/{user_email}"
7
        },
8
        storeId:"bc/account/store/{store_id}"
9
      }
10
    ) {
11
      storeId
12
    }
13
  }
14
}

Remove user from store

The following mutation removes a user from a store:

1
mutation {
2
  user {
3
    removeUserFromStore(
4
      input: {
5
        storeId: "bc/account/store/{store_hash}"
6
        userId: "bc/account/user/{user_id}"
7
      }
8
    ) {
9
      storeId,
10
      user {
11
        id
12
        email
13
        firstName
14
        lastName
15
        locale
16
      }
17
    }
18
  }
19
}

Resources

Articles

• Authentication and example requests
• Guide to API accounts