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
Name | Permission | Description |
---|---|---|
Account | read-only | View account details |
Account Stores | read | View the stores associated with an account |
Account Apps | read | View the apps associated with an account |
Account Users | read | View the users associated with an account |
Account Users | write | Create and update users |
Account Users | delete | Remove 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:
- 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.
- Use a GraphQL client such as Altair (opens in a new tab) to test the API.
- In the client, set the request URL to
https://api.bigcommerce.com/accounts/{account_uuid}/graphql
. - You can obtain the Account UUID identifier when creating the token or copy it from the API Path field.
- Send an
X-Auth-Token
request header with the access token as its value. - 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:
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
}
}
}
}