Users and roles

Employees who can spend on the company account, and the roles attached to them.

Roles are assigned here. They are defined by an enterprise administrator, outside this API — nothing on this host creates, edits or lists role definitions. So every operation below identifies a role by its id, and if you need a role that does not exist yet, an administrator has to create it before you can reference it.

Finding role ids

Read them off the members you already have. Every Member carries its assigned roles, each with its id, its name, and the permissions it grants:

query {
  users(first: 50) {
    nodes {
      userId
      userName
      roles { id name permissions }
    }
  }
}

roles is non-null and its entries are non-null, so a member always comes back with a list — possibly empty, never null. permissions is a list of EnterprisePermission enum values in SCREAMING_SNAKE_CASE — USERS_VIEW, SETTINGS_MANAGE and so on. A permission the platform no longer recognises is left out of the list.

Checking what a member can do

query {
  user(userId: 4271) {
    grantedPermissions
    canManageSettings: hasPermission(permission: SETTINGS_MANAGE)
  }
}

grantedPermissions is the union of the member's roles, deduplicated and with wildcards expanded, so a role holding ENTERPRISE_ALL contributes every permission that wildcard covers. hasPermission(permission:) answers for one value and is derived from the same list, so the two never disagree.

Both are advisory. They tell your UI what to offer; the server still checks the permission on every operation it gates.

A role becomes discoverable once someone holds it. This is the only place the API exposes role ids, so a freshly defined role that nobody has been assigned yet will not appear in any response. Ask the administrator who defined it for the id.

Inviting a user

mutation {
  inviteUser(
    email: "[email protected]"
    roleIds: [3]
  )
}

Note the shape: email and phone are both optional, while roleIds is required — you must supply at least one contact method, and the argument carrying the roles cannot be omitted. The list itself may be empty: roleIds: [] is accepted and invites the person with no role. A role id that is not live in your enterprise is rejected.

Returns a String — the invitation id, not a user object. To read the resulting member, query users.

Requires enterprise:users:write.

Listing members

query {
  users(first: 50, isActive: true) {
    nodes { id userId userEmail userName isActive }
    totalCount
    pageInfo { hasNextPage endCursor }
  }
}

Cursor-paginated (first/after forwards, last/before backwards), filterable by isActive, and the connection carries a totalCount that ignores pagination. user(userId:) fetches one.

A member has two ids, and every operation here takes the platform one. id identifies the enterprise membership record; userId identifies the platform user. user and every mutation below resolve on userId — passing id will not find the member you meant.

Requires enterprise:users:read.

Managing members

Mutation	Effect
`updateUser(userId:, input:)`	Change roles or active status; returns the `Member`
`suspendUser(userId:)`	Deactivate: block spending, keep the account; returns the `Member`
`activateUser(userId:)`	Restore a suspended user; returns the `Member`
`removeUser(userId:)`	Remove from the enterprise (soft delete); returns `true`
`resetUserPassword(userId:)`	Returns a temporary password

Requires enterprise:users:write.

updateUser is how you reassign roles. Its input has exactly two fields, roleIds and isActive, both optional, so an update can carry either or both:

mutation {
  updateUser(userId: 4271, input: { roleIds: [3, 7] }) {
    userId
    isActive
    roles { id name }
  }
}

roleIds replaces the member's roles wholesale — it does not merge. The assignments are cleared and rewritten from the list you send, so a member who holds roles 3 and 7 and is updated with roleIds: [3] comes back holding only role 3. Send the full set you want the member to end up with, not the delta. Omit roleIds entirely to leave the assignments untouched.

Suspend, do not remove, when someone leaves temporarily. Suspension stops spending while preserving the account and its history. Removal severs the association.

resetUserPassword echoes the temporary password once. It comes back in the mutation result and nothing else exposes it afterwards, so deliver it to the member over a secure channel as part of handling the response. If you drop it, the only recourse is another reset.

Enrolling people without inviting them one by one

An administrator can verify your email domain so that staff sign themselves up. That is set up by an administrator rather than through this API, so there is no operation here that configures it.

For a directory that stays in step on its own, sync members from your identity provider instead — see SCIM provisioning. A member created that way is an ordinary member: it appears in users, holds roles, and can be suspended here.

Reference

Generated reference — every type, field and argument, built from the live schema.

Enterprise organisation SCIM provisioning

Built with