Build apps around user roles

Your app can call the user role entity to get basic info about users who are part of a QuickBooks Online company file.

The user role entity tells you if users are admins or employees, active or inactive, and have access to features like Intuit or QuickBooks Payroll.

This also lets you build features around role-specific workflows. Since your app knows each user’s role, it also knows if they have permission to do certain tasks, like run payroll.

Step 1: Set up your app in the Intuit Developer Portal

If you haven’t already, get a QuickBooks Online sandbox company for testing and create your app.

Step 2: Set your app’s scopes

Intuit Ecosystem API uses scopes to limit the type of data your app can access. You’ll set the scope when you create your app.

For user role features, use these scopes:

com.intuit.identity.user.roles.read

Note: Apps need to be onboarded to scopes before they can start using them.

Step 3: Get your app’s credentials

Sign in to your developer account.
Select the Dashboard link on the toolbar.
Select and open your app.
In the Production section, select Keys & OAuth.
Copy the Client ID and Client Secret.

Step 4: Authorize your app

If you haven’t already, use your Client ID, Client Secret, and scopes to set up OAuth 2.0.

Step 5: Create a query for user role info

For this query, we’ll use the following entities:

User role

We’ll use the following fields:

Field	DataType	Description
realmId (*Required)	String	The company ID of the QuickBooks company the user belongs to.
type	Enum - enum roleType { ADMIN, EMPLOYEE }	The user's level of access in the given company, "Admin" or "Employee"
status	Enum - enum roleStatus { ACTIVE, INACTIVE }	The user's access status in the given company, "Active" or "Inactive"
hasPayroll	Boolean	Value will be "TRUE" if the company has the payroll feature turned on

Endpoints

Send POST requests to one of these endpoints.

Query header

Content-Type: application/json
Authorization: Use the user role scope [com.intuit.identity.user.roles.read] to get an access token and put the token in the request header

Query body

Here’s a basic query to get user role info:

 {
  user {
    role (realmId: "9130349878530396") {
      type
      status
      hasPayroll
    }
  }
}

You can include all of these fields, or add fields, depending on your app’s needs.

Note: The realmID field is the 16 digit company ID of the QuickBooks Online company you're requesting user role info for.

Sample server response

{
  "data": {
    "user": {
      "role": {
        "type": "ADMIN",
        "status": "ACTIVE",
        "hasPayroll": true
      }
    }
  }
}

The type and status field values define the user’s role. You’ll only see fields like hasPayroll if these features are active for the QuickBooks company.

Request user role for an invalid realm

If the realmID is incorrect, you’ll get the following response:

 {
  user {
    role (realmId: "9130349878530397") {
      type
      status
      hasPayroll
    }
  }
}

Sample sever response for an error

{
 "errors": [
   {
     "message": "User id not part of the realm!",
     "locations": [
       {
         "line": 3,
         "column": 3
       }
     ],
     "path": [],
     "extensions": {
       "code": "VAL-1002",
       "innerMessage": "User id not part of the realm!",
       "classification": "VALIDATION_ERROR"
     }
   }
 ]
}

Make sure the realmID is for the correct end-users’ QuickBooks Online company ID.

Step 6: Go live with your app

Follow these steps when you’re ready to publish your app. You don’t need to make it publicly available, but you need to publish it so it’s active.