Super Admins

Introduction

A Super Admin is a specialized user that has the ability to “masquerade” as an Admin user of one or more companies.

Super Admins and the companies they are assigned to are managed in the B2B admin. As a user operating from the storefront, a Super Admin corresponds with a BigCommerce customer account. When such a customer logs in, they can then begin masquerading for one of their assigned companies from the storefront context, and thereafter they can access the same data and take the same storefront actions as one of that company’s users with the Admin role.

The masquerade process involves an update to the user’s customer account to actually change their customer group to the one assigned to the chosen company (if any), in order to ensure that the Super Admin sees accurate pricing for that company when browsing the storefront.

The B2B GraphQL API includes queries and mutations for the storefront interactions of a Super Admin.

Logging In as a Super Admin

Since a Super Admin is associated with a customer account, logging in works exactly the same way as for a company user. Simply use the login mutation with the correct credentials of a Super Admin customer.

Example query:

mutation LogIn(
    $storeHash: String!,
    $email: String!,
    $password: String!
) {
    login(
        loginData: {
            storeHash: $storeHash,
            email: $email,
            password: $password
        }
    ) {
        result {
            token
        }
    }
}

As with any company user, you should retain the returned token and use it as the Bearer token value for future GraphQL requests, including those for interacting with the masquerade function, to establish the Super Admin as the user context.

Fetching the Super Admin’s Companies

The superAdminCompanies query can be used to fetch the details of the companies assigned to the current user.

Example query and response:

query GetSuperAdminCompanies(
    $superAdminId: Int!
) {
    superAdminCompanies(
        superAdminId: $superAdminId
    ) {
        pageInfo {
            hasNextPage
            hasPreviousPage
            startCursor
            endCursor
        }
        totalCount
        edges {
            node {
                companyId
                companyName
                companyAdminName
                companyEmail
            }
        }
    }
}

Note that the ID passed in the superAdminId argument is the B2B user ID, as returned by the login mutation.

Masquerading

Once a Super Admin login has been performed and the resulting Bearer token is being used, a set of GraphQL operations make it possible to manage which company the user is masquerading as.

Beginning a Masquerade

Use the superAdminBeginMasquerade mutation to specify which company the current user (Super Admin) should currently masquerade as.

Example mutation and response:

mutation BeginMasquerade(
    $companyId: Int!,
    $userId: Int!
) {
    superAdminBeginMasquerade(
        companyId: $companyId,
        userId: $userId
    ) {
        userInfo {
            email
            firstName
            lastName
            phoneNumber
        }
    }
}

Pass the same B2B user ID matching the Super Admin user for the userId argument and the ID of the desired company for companyId.

Once the masquerade has been established, any of the other typical queries and mutations performed with a Bearer token belonging to the user will be equivalent to the context of an Admin user belonging to that company.

Inspecting the Current Masquerade

The superAdminMasquerading query can be used to fetch details on the company the current user is currently masquerading as.

Example query and response:

query GetMasqueradeInfo(
    $customerId: Int!
) {
    superAdminMasquerading(
        customerId: $customerId
    ) {
        id
        companyName
        addressLine1
        addressLine2
        city
        state
        zipCode
        country
    }
}

Note that in this case, unlike with superAdminBeginMasquerade, it is the BigCommerce customer ID of the Super Admin, not the B2B user ID, that should be passed in for the customerId argument.

Ending a Masquerade

When a Super Admin no longer needs to masquerade as any company, it is best practice to explicitly end the masquerade using the superAdminEndMasquerade mutation.

Example mutation and response:

mutation EndMasquerade(
    $companyId: Int!,
    $userId: Int!
) {
    superAdminEndMasquerade(
        companyId: $companyId,
        userId: $userId
    ) {
        message
    }
}

Note that the userId argument here expects the B2B user ID.

While companyId is a required argument, performing this mutation will end the current user’s masquerade regardless of the value provided.

Once a masquerade is ended, the result of any queries or mutations using the Super Admin’s Bearer token will be as if the user does not belong to the associated company or does not have sufficient permissions.

GraphQL Requests While Masquerading

When a masquerade has been started for a Super Admin, all queries and mutations will operate identically to the way they would for an Admin user belonging to the company in question. Simply use the Bearer token from a login by the Super Admin, as you would for any company user.

For example, the query we’ve previously seen for inspecting the company’s orders can be run:

query GetOrders {
    allOrders {
        pageInfo {
            hasNextPage
            hasPreviousPage
            startCursor
            endCursor
        }
        totalCount
        edges {
            node {
                id
                bcOrderId
                createdAt
                userId
                bcCustomerId
                ...
            }
        }
    }
}

This will successfully return a list of orders, and only those orders belonging to the company associated with the current masquerade. Mutations such as those for creating a new user, initiating a checkout from a quote, or initiating a checkout from an invoice will function as expected, too, giving a Super Admin the ability to perform any storefront actions.