Docs
Account API
Users overview

GraphQL Account API: Users 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.

OAuth scopes

NamePermissionDescription
Accountread-onlyView account details
Account StoresreadView the stores associated with an account
Account AppsreadView the apps associated with an account
Account UsersreadView the users associated with an account
Account UserswriteCreate and update users
Account UsersdeleteRemove users

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 (opens in a new tab) 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:

GraphQL Account API 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:

Example query: Get account details
query {
  account {
    id
    accountInfo {
      name
    }
  }
}

Account users

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

Example query: Get account users
query {
  account {
    id
    users {
      edges {
        node {
          id
          email
          firstName
          lastName
        }
      }
    }
  }
}

Account stores users

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

Example query: Get account stores users
query {
  account {
    id
    stores {
      edges {
        node {
          id
          name
          storeHash
          users {
              collectionInfo {
                totalItems
              }
            edges {
              node {
                id
                email
                firstName
                lastName
                locale
                lastLoginAt
                permissions
                status
                updatedAt
                apps {
                  edges {
                    node {
                      id
                      name
                    }
                  }
                }
              }
            }
          }
          apps {
            edges {
              node {
                id
                name
              }
            }
          }
        }
      }
    }
  }
}

Account apps

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

Example query: Get account apps
query {
  account {
    id
    apps {
      edges {
        node {
          id
          name
        }
      }
    }
  }
}

Add user to account

The following mutation adds a user to an account:

Example mutation: Add user to account
mutation {
  account {
    addUserToAccount(
      input: {
        email: "jane.doe@example.com"
      }
    ) {
      account {
        accountInfo {
          name
        }
      }
    }
  }
}

Remove user from account

The following mutation removes a user from an account:

Example mutation: Remove user from account
mutation {
  account {
    removeUserFromAccount(
      input: {
        email: "jane.doe@example.com"
      }
    ) {
      accountId,
      userId
    }
  }
}

Create user

The following mutation creates a user:

Example mutation: Create a user
mutation {
  user {
    createUserWithPassword(
      input: {
        email: "jane.doe@example.com",
        firstName: "Jane",
        lastName: "Doe",
        locale: "en-US",
        password: "Password1234!",
        passwordConfirmation: "Password1234!"
      }
    ) {
      user {
        id
      }
    }
  }
}

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:

Example mutation: Add user to store
mutation {
  user {
    addUserToStore(
      input: {
        user: {
          id: "bc/account/user/{user_id}"
        },
        storeId:"bc/account/store/{store_id}"
      }
    ) {
      storeId
    }
  }
}

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

Example mutation: Add user to store
mutation {
  user {
    addUserToStore(
      input: {
        user: {
          email: "bc/account/user/{user_email}"
        },
        storeId:"bc/account/store/{store_id}"
      }
    ) {
      storeId
    }
  }
}

Remove user from store

The following mutation removes a user from a store:

Example mutation: Remove user from store
mutation {
  user {
    removeUserFromStore(
      input: {
        storeId: "bc/account/store/{store_hash}"
        userId: "bc/account/user/{user_id}"
      }
    ) {
      storeId,
      user {
        id
        email
        firstName
        lastName
        locale
      }
    }
  }
}

Resources

Articles

Did you find what you were looking for?