Enterprise permissions

Enterprise permissions is BigCommerce’s group-based access control system. It replaces per-user permission checkboxes with reusable user groups, predefined policy bundles, and per-store targets. A user’s effective access is the union of every policy granted by every group they belong to.

This guide covers the GraphQL operations that extend the Account API during the closed beta. These operations let you add and remove users from user groups, list groups, and audit group memberships per group or per user. For the GA operations on the same endpoint (creating users, adding users to stores), see the GraphQL Account API overview.

How enterprise permissions works

The permission model has three concepts:

1. User groups — Named, reusable bundles of access. For example, Warehouse, Sales Rep, Finance.
2. Policies — Predefined permission bundles such as Orders Read or Account Users Manage. Policies are granted to groups, not to individual users.
3. Targets — The resource a policy applies to: a specific store, or the account itself.

A user belongs to zero or more groups. Their effective permissions are the union of the policies granted by every group they belong to.

A default Account Administrators group is provisioned with each account and grants account-level access. Store owners and other account admins must remain members of this group to keep account-level permissions after enterprise permissions is enabled.

Before you begin

Substitute your account UUID for {account_uuid}. Your BigCommerce contact provides the UUID during onboarding.

Configure user groups via the API

The user-group operations live in the userGroup mutation namespace and as fields on the account query. The examples below send a single GraphQL operation per request to the endpoint above.

Pagination

account.userGroups and account.users are Relay-style connections. Each result is wrapped in edges { cursor node { ... } }, and large result sets are returned in pages. To page through results, pass first and after arguments on the connection (for example, userGroups(first: 50, after: "<cursor>")) and use the cursor of the last node returned as the after value for the next request. Both connections also expose a standard pageInfo { hasNextPage endCursor } selector.

Add users to user groups

Adds one or more users to one or more groups. Returns a pollingId for tracking large batch operations. The field may return an empty string when the operation completes synchronously.

1
mutation UserGroup {
2
  userGroup {
3
    addUsersToUserGroups(
4
      input: {
5
        userIds: [
6
          "bc/account/user/1956612"
7
          "bc/account/user/1364558"
8
          "bc/account/user/2393917"
9
        ]
10
        userGroupIds: [
11
          "bc/account/userGroup/cab76766-5af9-416c-9edd-0f5da0e003b4"
12
          "bc/account/userGroup/9fe52bbe-827a-4712-bf76-ebd4d2465277"
13
        ]
14
      }
15
    ) {
16
      pollingId
17
    }
18
  }
19
}

Remove users from a user group

Removes one or more users from a single group. Returns the users that were removed, for confirmation.

1
mutation UserGroup {
2
  userGroup {
3
    removeUsersFromUserGroup(
4
      input: {
5
        userIds: [
6
          "bc/account/user/1956612"
7
          "bc/account/user/1364558"
8
          "bc/account/user/2393917"
9
        ]
10
        userGroupId: "bc/account/userGroup/9fe52bbe-827a-4712-bf76-ebd4d2465277"
11
      }
12
    ) {
13
      users {
14
        edges {
15
          cursor
16
          node {
17
            id
18
            email
19
            firstName
20
            lastName
21
            locale
22
          }
23
        }
24
      }
25
    }
26
  }
27
}

List user groups in an account

Returns every group in the account with its ID, name, and description. Use this to discover the userGroupId values needed for mutations.

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

View group membership

Returns every group with its members nested. Use this to audit who belongs to which group.

1
query Account {
2
  account {
3
    userGroups {
4
      edges {
5
        node {
6
          id
7
          name
8
          description
9
          users {
10
            edges {
11
              cursor
12
              node {
13
                id
14
                email
15
                firstName
16
                lastName
17
                locale
18
              }
19
            }
20
          }
21
        }
22
      }
23
    }
24
  }
25
}

View group memberships per user

Returns every user with the groups they belong to nested. Use this to audit a single user’s effective access surface.

1
query Account {
2
  account {
3
    users {
4
      edges {
5
        node {
6
          id
7
          email
8
          firstName
9
          lastName
10
          locale
11
          userGroups {
12
            edges {
13
              node {
14
                id
15
                name
16
                description
17
              }
18
            }
19
          }
20
        }
21
      }
22
    }
23
  }
24
}

Constraints

• Account scope — Enterprise permissions is an account-level feature. Enabling it affects every store in the account.
• Subject to change — The beta API may change during the beta. We will communicate breaking changes in advance, but treat the schema as unstable.
• Concurrent edits — Concurrent updates to the same user group or user can produce race conditions. Coordinate changes between scripts or operators.
• Default group membership — Store owners and account admins must remain members of the Account Administrators group to keep account-level permissions.
• Store and ownership transfers — Store owner transfers and store transfers require manual BigCommerce involvement while the beta is enabled. Contact your BigCommerce account team before initiating either.
• Opt-out — Opting out of the beta requires BigCommerce involvement and may require store-level permissions to be repaired afterward.

Resources

• GraphQL Account API overview — GA operations on the same endpoint, including user creation and store-level user management.
• API accounts — how to create the account-level API account whose token authenticates these calls.
• Rate limits — quota details for the /accounts/* endpoints.

Feedback

Send beta feedback, change requests, and onboarding questions to your CSM or TAM. Feedback on usability, missing functionality, and confusing behavior is especially valuable during the closed beta.