Guides
BlogAbout

Users, Teams, and Roles (GQL)

Suggest Edits

Get a user's details

This query returns a user's information. You can obtain any user's information if you call this query from your personal context. If you call this query from a team context, you must include your API key from your personal account in the x-rapidapi-identity-key header.

query Users($where: UserWhereInput!) {
  users(where: $where) {
    nodes {
      id
      username
      name
      email
      createdAt
      status
      Teams{
        id
        name
      }
    }
  }
}

To query by a user's email:

{
  "where": {
    "email": "USER_EMAIL"
  }
}

To query by a user's user name:

{
  "where": {
    "username": 'USER_NAME'
  }
}

To query by one or more user id:

{
  "where": {
    "userIds": [
      6049746,
      5713300
    ]
  }
}

Here is a Node.js version of the above query.

const axios = require("axios");

const options = {
  method: "POST",
  url: "YOUR URL FROM SAMPLE CODE",
  headers: {
    "content-type": "application/json",
    "X-RapidAPI-Key": "YOUR KEY FROM SAMPLE CODE",
    "X-RapidAPI-Host": "YOUR HOST FROM SAMPLE CODE",
  },
  data: {
    query: `query Users($where: UserWhereInput!) {
  users(where: $where) {
    nodes {
      id
      username
      name
      email
      createdAt
      status
      Teams{
        id
        name
      }
    }
  }
}`,
    variables: { where: { email: "USER_EMAIL" } },
  },
};

axios
  .request(options)
  .then(function (response) {
    console.log(JSON.stringify(response.data));
  })
  .catch(function (error) {
    console.error(error);
  });

Here is the same query, but the response includes the teams that the user is a member of, as well as the personal and team apps the user has access to. Apps are called Projects in the GraphQL Platform API.

query Users($where: UserWhereInput!) {
  users(where: $where) {
    id
    username
    name
    email
    createdAt
    status
    ProjectAcls{
      Project{
        name
        id
        description
      }
    }
    Teams{
      id
      name
      ProjectAcls{
        Project{
          name
          id
          description
        }
      }
    }
  }
}

{
  "where": {
    "email": "[email protected]"
  }
}

{
  "where": {
    "userIds": [
      6049746,
      5713300
    ]
  }
}

Get a single user's details (admin)

Environment Admins can query for details of any user in the Enterprise Hub. This query is used in the Users tab of the Admin Panel.

📘

Environment Admin from personal account

This query only works if you are an Environment Admin. Currently, you must execute this query from your Personal Account (not a team account). This means if the GraphQL Platform API is private, you must personally be invited to use the API.

  query user($id: ID!) {
   user(id: $id) {
    id
    name
    thumbnail
    mashapeId
    createdAt
    updatedAt
    email
    status
    username
    verified
    apisCount
    singleAdminOrgs
    organizations {
      id
      name
      description
    }
    role { 
      roleId
    }
    protected
    Teams {
      id
      name
      createdAt
      thumbnail
    }
    ProjectAcls {
      id
      createdAt
      Project {
        id
        name
        applicationAuthorizations {
          id
          key
        }
      }
    }
  }
}

  {
      "id": 7344547
  }

Get details for multiple users (admin)

Environment Admins can query for some or all users of the Enterprise Hub. This query is used in the Users tab of the Admin Panel. The term field in the variables can be used to limit the search to specific usernames, emails, or IDs. This is the same as specifying a value in the search box on the Users tab of the Admin Panel. This query uses Pagination (GQL) to manage the results.

📘

Environment Admin from personal account

This query only works if you are an Environment Admin. Currently, you must execute this query from your Personal Account (not a team account). This means if the GraphQL Platform API is private, you must personally be invited to use the API.

query getUsers($where: UserWhereInput!) {
  users(where: $where) {
    totalCount
    nodes {
      name
      username
      id
      thumbnail
      email
      createdAt
      lastActive
      apisCount
      status
    }
  }
}

{
  "where": {
    "limit": 50,
    "offset": 0,
    "term": "",
    "order": "createdAt,ASC",
    "byField": "id,name,email,username",
    "filters": {}
  }
}

Update a user's details

Use the updateUser mutation to update a user's details, such as their user status (for example, to deactivate a user). You must specify the user's id in the variables.

You can set a user's status to ACTIVE, DEACTIVATED, or DELETED.

The following example deactivates a user:

mutation updateUser($input: UserUpdateInput!) {
  updateUser(input: $input) {
    status
  }
}

{
  "input": {
    "status": "DEACTIVATED",
    "id": 7344540
  }
}

Get the users of an organization

📘

You can also obtain an organization's users using query.organization or query.organizations. See Organizations (GQL).

This query returns the users of the organization. This query must be made from a team context. The user making the query must be a member of the organization. This user's personal API key must be specified in the x-rapidapi-identity-key header. You must specify the orgId as input. This can be obtained using this query.

Notice that this query uses pagination (GQL).

query PaginatedTeamUsersByOrganizationIdV2($orgId: Int!, $pagingArgs: PagingArgs) {
  paginatedTeamUsersByOrganizationIdV2(orgId: $orgId, pagingArgs: $pagingArgs) {
    data {
      id
      name
      username
      email
      role
      inviteStatus
    }
    total
    totalActive
  }
}

{
  "orgId": 5755578,
  "pagingArgs": {
    "offset": 0,
    "limit": 1000,
    "orderBy": "id",
    "orderDirection": "desc"
  }
}

Get a team's details

📘

You can also obtain team details using query.organization or query.organizations. See Organizations (GQL).

This query returns a teams's information. You can obtain any team's information if you are a member of the team and call this query from your personal context. If you call this query from a team context, you must be a member of the team that you are querying and include your API key from your personal account in the x-rapidapi-identity-key header. In the GraphQL API, apps are known as projects. The ProjectAcls portion of this query lists the teams apps.

query Team($id: ID!) {
  team(id: $id) {
      id
      slugifiedName
      name
      createdAt
      ProjectAcls {
        Project {
          id
          name
        }
      }
    }
}

To query by a team's id:

{
  "id": "6631475"
}

Get configured roles

query Roles($where: RoleWhereInput!) {
  roles(where: $where) {

    edges {
      node {
        id
        name
        permissions {
          id
          rolePermission {
          granted
          readOnly
        }
        }
      }
      cursor
    }
    pageInfo {
      hasNextPage
      hasPreviousPage
      startCursor
      endCursor
    }
  }
}

{
  "where": {"roleLevels": ["USER_ENVIRONMENT"]}
}

Update a user's organization role

In the variables, specify the user id in the entityId field.

mutation UpdateUserRoles($input: UserRolesUpdateInput) {
  updateUserRoles(input: $input)
}

{
  "input": {
    "entityId": 6049746,
    "roleId": 580,
    "orgId": 7669830
  }
}

Update a user's team role

In the variables, specify the user id in the entityId field. Specify the team id in the parentId field.

mutation upsertEntityRole($input: EntityRoleInput) {
  upsertEntityRole(input: $input)
}

{
  "input": {
    "entityId": 6049746,
    "roleId": 627,
    "orgId": 7669830,
    "parentId": 7669831
  }
}

Get a user's teams

Returns an array of teams of an org. The API requestor must be a member of the org. In Variables, you must pass either the orgId or the org's slugifiedName. See Organizations (GQL).

query Teams($where: TeamWhereInput!) {
  teams(where: $where) {
    name
    id
    slugifiedName
  }
}

{
  "where": {
    "orgId": YOUR_ORG_ID
  }
}

Invite a user to an organization

mutation CreateUserInvites($input: UserInvitesInput) {
  createUserInvites(input: $input)
}

{
  "input": {
    "email": "String",
    "teamIds": "[Int]!",
    "organizationId": "Int",
    "role": "String",
    "id": "Int",
    "inviterId": "Int"
  }
}

Manage team users (add, remove, change role)

To add a user to a team, use the teamToAdd field in the Variables. teamToRemove and newRole are optional.

To delete a user from a team, use the teamToRemove field in the Variables. teamToAdd and newRole are optional.

To change a user's role, use the newRole field.

You can obtain the user's ID (teamUserId) from the Admin Panel. You can obtain the orgID and team IDs from the Organization dashboard. 

mutation UpdateTeamUser($input: TeamUserUpdateInput) {
  updateTeamUser(input: $input)
}

{
  "input": {
    "orgId": Int,
    "teamUserId": Int,
    "teamToRemove": Int,
    "teamToAdd": Int,
    "newRole": "String"
  }
}

Updated 5 months ago