GraphQL Users API Overview

Introduction

The GraphQL Users API is an account-level GraphQL API that allows you to 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 Users API, 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

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 Users API introduces a new way to manage control panel users. Using an OAuth-based API account, you can integrate our APIs with your current system to create a custom experience.

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 Users API 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:

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.

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:

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:

query {
  account {
    id
    apps {
      edges {
        node {
          id
          name
        }
      }
    }
  }
}

Add user to account

The following mutation adds a user to an 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:

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

Create user

The following mutation creates 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:

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:

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:

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

• Authentication and Example Requests
• Guide to API Accounts