---
title: NerdGraph tutorial: Manage groups and users
source: https://docs.newrelic.com/docs/apis/nerdgraph/examples/nerdgraph-manage-groups
---

You can use our [NerdGraph API](https://docs.newrelic.com/docs/apis/nerdgraph/get-started/introduction-new-relic-nerdgraph) to view and manage user groups and what those groups can access. For how to do this in the UI, see the [user management UI docs](https://docs.newrelic.com/docs/accounts/accounts-billing/new-relic-one-user-management/user-management-ui-and-tasks).

To use NerdGraph to create users, and view their information, see [Manage users with NerdGraph](https://docs.newrelic.com/docs/apis/nerdgraph/examples/nerdgraph-manage-users).

## Requirements [#requirements]

Some requirements for managing users and groups via NerdGraph:

-   [Pro or Enterprise edition](https://newrelic.com/pricing) is required to customize user groups and roles
-   If you're using [SCIM provisioning](https://docs.newrelic.com/docs/accounts/accounts/automated-user-management/automated-user-provisioning-single-sign): for that authentication domain, you can't create groups or add users to groups, because your groups and users are managed via SCIM.
-   [User type](https://docs.newrelic.com/docs/accounts/accounts-billing/new-relic-one-user-management/user-type): core user or full platform user
-   [Role](https://docs.newrelic.com/docs/accounts/accounts-billing/new-relic-one-user-management/user-management-concepts/#roles): **Authentication Domain Manager**

## Before you start [#concepts]

Before using NerdGraph to manage users:

-   Ensure you have a decent understanding of our [user management concepts](https://docs.newrelic.com/docs/accounts/accounts-billing/new-relic-one-user-management/user-management-concepts#understand-concepts)
-   If you haven't already, we suggest looking in the **Access management** UI to improve your understanding of how groups and user access works, and to understand groups that already exist. Before you do this, we recommend creating a plan for the group access you need to create: here's [an example planning spreadsheet](https://docs.google.com/spreadsheets/d/1FnguDXRUX9FGY14oV4Gx6O08v4vNC2Pv0GGCsU7Pxuw/edit?usp=sharing).
-   Note that the [NerdGraph explorer](https://docs.newrelic.com/docs/apis/nerdgraph/get-started/introduction-new-relic-nerdgraph/#explorer) has built-in docs that define the fields used in these requests.
-   Note that you can [track changes to your New Relic account](https://docs.newrelic.com/docs/data-apis/understand-data/event-data/query-account-audit-logs-nrauditevent).

## Suggested workflow for creating groups [#flow]

You can use these queries and mutations in various ways and in various orders, but here's one common workflow for setting up groups:

1.  [Query your users' information](#query-users) and [available roles](#query-roles): this can be a helpful first place to start to make sure you understand what users you have in New Relic and the available roles. If you're just starting out, you may not have added users yet, and you may have only our standard roles.
2.  [Optional: Create a new group](#create-group): **Not available if using SCIM provisioning.** You can either use existing groups or create a new group. After creating a group, you must grant it access to roles and accounts. Note that a group, on its own, doesn't grant any access to users in that group: it's only when it has a role and account assigned that users can actually access New Relic.
3.  [Grant access to a group](#grant-access): this is what assigns groups access to roles and to accounts.

When you're done, if there are already users in the group you've created and that group has access to at least one role and account, they should have access within a few minutes (although for [EU and JP region New Relic accounts](https://docs.newrelic.com/docs/using-new-relic/welcome-new-relic/get-started/our-eu-us-region-data-centers), this can take up to 20 minutes or so). If your users are not yet in that group (which would be true if you just created a new group), you can [add users to that group](https://docs.newrelic.com/docs/accounts/accounts-billing/new-relic-one-user-management/account-user-mgmt-tutorial#add-users).

## Query groups [#query-groups]

Here's an example of querying for existing groups in a given authentication domain:

```graphql
{
  actor {
    organization {
      userManagement {
        authenticationDomains(id: "YOUR_AUTHENTICATION_DOMAIN_ID") {
          authenticationDomains {
            groups {
              groups {
                displayName
                id
              }
            }
          }
        }
      }
    }
  }
}
```

## Query existing roles [#query-roles]

Here's an example of returning information about roles:

```graphql
{
  actor {
    organization {
      authorizationManagement {
        authenticationDomains {
          authenticationDomains {
            groups {
              groups {
                roles {
                  roles {
                    accountId
                    displayName
                    id
                    name
                    organizationId
                    type
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}
```

Here's an example result:

```json
{
  "data": {
    "actor": {
      "organization": {
        "authorizationManagement": {
          "authenticationDomains": {
            "authenticationDomains": [
              {
                "groups": {
                  "groups": [
                    {
                      "roles": {
                        "roles": [
                          {
                            "accountId": "account-id",
                            "displayName": "name",
                            "id": "id",
                            "name": "role-name",
                            "organizationId": null,
                            "type": "role-type"
                          },
                          {
                            "accountId":null,
                            "displayName": "name",
                            "id": "id",
                            "name": "role-name",
                            "organizationId": "organization-id",
                            "type": "role-type"
                          }
                        ]
                      }
                    }
                  ]
                }
              }
            ]
          }
        }
      }
    }
  }
}
```

## Query users [#query-users]

### Query user information [#query-user-info]

Here's an example of querying information about your users:

```graphql
{
  actor {
    organization {
      userManagement {
        authenticationDomains {
          authenticationDomains {
            groups {
              groups {
                users {
                  users {
                    id
                    email
                    name
                    timeZone
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}
```

Here's an example result:

```json
{
  "data": {
    "actor": {
      "organization": {
        "userManagement": {
          "authenticationDomains": {
            "authenticationDomains": [
              {
                "groups": {
                  "groups": [
                    {
                      "users": {
                        "users": [
                          {
                            "email": "example@newrelic.com",
                            "id": "123456789",
                            "name": "Example Relic",
                            "timeZone": "Etc/UTC"
                          }
                        ]
                      }
                    }
                  ]
                }
              }
            ]
          }
        }
      }
    }
  }
}
```

### Query your users' group memberships [#query-user-groups]

Here's an example of querying the groups your users belong to:

```graphql
{
  actor {
    organization {
      userManagement {
        authenticationDomains {
          authenticationDomains {
            users {
              users {
                groups {
                  groups {
                    displayName
                  }
                }
                email
              }
            }
          }
        }
      }
    }
  }
}
```

Here's an example response:

```json
{
  "data": {
    "actor": {
      "organization": {
        "userManagement": {
          "authenticationDomains": {
            "authenticationDomains": [
              {
                "users": {
                  "users": [
                    {
                      "email": "pete@example.com",
                      "groups": {
                        "groups": [
                          {
                            "displayName": "Admin"
                          },
                          {
                            "displayName": "Basic Sub Account"
                          }
                        ]
                      }
                    },
```

## Create a role [#create-role]

Before you create a custom role, you have to identify the permissions you want to assign to it.

### Retrieve permission IDs

Use the following query to retrieve the list of account-scoped permissions:

```graphql
query {
  customerAdministration {
    permissions {
      items {
        category
        feature
        id
        product
        subsetIds
      }
      nextCursor
    }
  }
}
```

For permissions scoped to an organization, run the following query instead:

```graphql
query {
  customerAdministration {
    permissions(filter: {scope: {eq: "organization"}}) {
      items {
        category
        feature
        id
        product
        subsetIds
      }
      nextCursor
    }
  }
}
```

Note the following fields:

-   `items`: An array of permission objects, each containing the following attributes:
    -   `category`: (String) The category or grouping the permission belongs to.
    -   `feature`: (String) The specific feature the permission is associated with.
    -   `id`: (String) A unique identifier for each permission.
    -   `product`: (String) The product that the permission applies to.
    -   `subsetIds`: (Array) A list of IDs representing subsets or related permissions.

### Create the custom role

After you have the unique identifier for each permission you want to assign to the new role, use the following mutation to create a [role](https://docs.newrelic.com/docs/accounts/accounts-billing/new-relic-one-user-management/user-management-concepts/#roles). You can create roles at three different scopes: account, organization, or entity level. The type of role you create must match the scope of the permissions you're assigning.

#### Account-scoped role

```graphql
mutation {
  customRoleCreate(
    container: {
      id: "YOUR_ORGANIZATION_ID"
      type: "ORGANIZATION"
    }
    name: "MY CUSTOM ACCOUNT ROLE"
    permissionIds: [1, 2, 3]
    scope: "account"
  ) {
    id
  }
}
```

#### Organization-scoped role

```graphql
mutation {
  customRoleCreate(
    container: {
      id: "YOUR_ORGANIZATION_ID"
      type: "ORGANIZATION"
    }
    name: "MY CUSTOM ORGANIZATION ROLE"
    permissionIds: [4, 5, 6]
    scope: "organization"
  ) {
    id
  }
}
```

#### Entity-scoped role

```graphql
mutation {
  customRoleCreate(
    container: {
      id: "YOUR_ORGANIZATION_ID"
      type: "ORGANIZATION"
    }
    name: "MY CUSTOM ENTITY ROLE"
    permissionIds: [7, 8, 9]
    scope: "entity"
  ) {
    id
  }
}
```

### Parameters

-   `container`:
    -   `id`: (String) The unique identifier of your organization. Replace `YOUR_ORGANIZATION_ID` with your actual organization ID.
    -   `type`: (String) The type of container. Currently, the only supported type is `"ORGANIZATION"`.
-   `name`: (String) The name assigned to the custom role.
-   `permissionIds`: (Array) A list of permission IDs representing the capabilities assigned to the custom role. Use the IDs retrieved from the permissions query above.
-   `scope`: (String) The level at which the role's permissions apply. Supported values:
    -   `"account"`: Role permissions apply at the account level
    -   `"organization"`: Role permissions apply at the organization level
    -   `"entity"`: Role permissions apply at the entity level

### Response

-   `id`: Returns the unique ID of the newly created custom role.

    > #### ⚠️ IMPORTANT
    >
    > -   Replace `YOUR_ORGANIZATION_ID` with your specific organization ID before executing the mutation.
    > -   Replace the example `permissionIds` with the actual permission IDs you retrieved from the permissions query.
    > -   Ensure that the permission IDs you use match the scope you're creating. Use organization-scoped permissions for organization roles and account-scoped permissions for account roles.

## Update role [#update-role]

Here's an example of updating a [role](https://docs.newrelic.com/docs/accounts/accounts-billing/new-relic-one-user-management/user-management-concepts/#roles).

```graphql
mutation {
  customRoleUpdate(
    id: ROLE_ID
    name: "MY NEW CUSTOM ROLE NAME"
    permissionIds: [4,5,6] 
  ) {
    id
  }
}
```

### Parameters

-   `id`: The unique identifier of the custom role you wish to modify. Replace `ROLE_ID` with the actual ID of the role.
-   `name`: The new name you want to assign to the custom role. In this example, it's `MY NEW CUSTOM ROLE NAME`.
-   `permissionIds`: An array of permission IDs you want to assign to this role. Ensure these IDs are valid and correspond to the permissions you intend to implement.

## Delete a role [#delete-role]

Here's an example of deleting a [role](https://docs.newrelic.com/docs/accounts/accounts-billing/new-relic-one-user-management/user-management-concepts/#roles):

```graphql
mutation {
  customRoleDelete(
    id: ROLE_ID 
  ) {
    id
  }
}
```

### Parameters

-   `id`: The unique identifier of the role you wish to delete. Replace `ROLE_ID` with the actual ID of the role you want to remove.

### Response

-   `id`: Returns the ID of the role that has been deleted, confirming the successful execution of the mutation.

## Create a group [#create-group]

Here's an example of creating a [group](https://docs.newrelic.com/docs/accounts/accounts-billing/new-relic-one-user-management/user-management-concepts/#groups):

```graphql
mutation {
  userManagementCreateGroup(
    createGroupOptions: {
      authenticationDomainId: "YOUR_AUTH_DOMAIN_ID"
      displayName: "GROUP_DISPLAY_NAME"
    }
  ) {
    group {
      displayName
      id
    }
  }
}
```

Successful response:

```json
{
  "data": {
    "userManagementCreateGroup": {
      "group": {
        "displayName": "GROUP_DISPLAY_NAME"
	      "id": "GROUP_ID"
      }
    }
  }
}
```

## Update user group [#update-group]

Here's an example of updating a [group](https://docs.newrelic.com/docs/accounts/accounts-billing/new-relic-one-user-management/user-management-concepts/#groups).

```graphql
mutation {
  userManagementUpdateGroup(
    updateGroupOptions: {
      displayName: "YOUR_UPDATED_GROUP_NAME"
      id: "YOUR_GROUP_ID"
    }
  ) {
    group {
      id
      displayName
    }
  }
}
```

Response for success:

```json
{
  "data": {
    "userManagementUpdateGroup": {
      "group": {
        "displayName": "YOUR_UPDATED_GROUP_NAME",
        "id": "GROUP_ID"
      }
    }
  }
}
```

Response for failure:

```json
{
  "data": {
    "userManagementUpdateGroup": null
  },
  "errors": [
    {
      "extensions": {
        "errorClass": "SERVER_ERROR"
      },
      "locations": [
        {
          "column": 3,
          "line": 2
        }
      ],
      "message": "Group could not be found",
      "path": [
        "userManagementUpdateGroup"
      ]
    }
  ]
}
```

## Delete a group [#delete-group]

Here's an example of deleting a [group](https://docs.newrelic.com/docs/accounts/accounts-billing/new-relic-one-user-management/user-management-concepts/#groups):

```graphql
mutation {
  userManagementDeleteGroup(groupOptions: {id: "YOUR_GROUP_ID"}) {
    group {
      id
    }
  }
}
```

Response for success:

```json
{
  "data": {
    "userManagementDeleteGroup": {
      "group": {
        "id": "GROUP_ID"
      }
    }
  }
}
```

Response for failure:

```json
{
  "data": {
    "userManagementDeleteGroup": null
  },
  "errors": [
    {
      "extensions": {
        "errorClass": "SERVER_ERROR"
      },
      "locations": [
        {
          "column": 3,
          "line": 2
        }
      ],
      "message": "Couldn't find Group with 'id'='ENTERED_GROUP_ID",
      "path": [
        "userManagementDeleteGroup"
      ]
    }
  ]
}
```

## Add users to groups [#add-users]

Here's an example of adding users to groups:

```graphql
mutation {
  userManagementAddUsersToGroups(
    addUsersToGroupsOptions: {
      groupIds: [FIRST_GROUP_ID, SECOND_GROUP_ID]
      userIds: [YOUR_USERS_IDS]
    }
  ) {
    groups {
      displayName
      id
    }
  }
}
```

Response for success:

```json
{
  "data": {
    "userManagementAddUsersToGroups": {
      "groups": [
        {
          "displayName": "GROUP_1_NAME",
          "id": "GROUP_ID_1"
        },
        {
          "displayName": "GROUP_NAME_2",
          "id": "GROUP_ID_2"
        }
      ]
    }
  }
}
```

Response for failure:

```json
{
  "data": {
    "userManagementAddUsersToGroups": null
  },
  "errors": [
    {
      "extensions": {
        "errorClass": "SERVER_ERROR"
      },
      "locations": [
        {
          "column": 3,
          "line": 2
        }
      ],
      "message": "The following ids were not found: group_ids: 'NON_EXISTENT_GROUP_ID'",
      "path": [
        "userManagementAddUsersToGroups"
      ]
    }
  ]
}
```

## Remove users from groups [#remove-users]

Here's an example of removing users from groups:

```graphql
mutation {
  userManagementRemoveUsersFromGroups(
    removeUsersFromGroupsOptions: {
      groupIds: [YOUR_GROUP_IDS]
      userIds: [YOUR_USER_IDS]
    }
  ) {
    groups {
      displayName
      id
    }
  }
}
```

Response for success:

```json
{
  "data": {
    "userManagementRemoveUsersFromGroups": {
      "groups": [
        {
          "displayName": "YOUR_GROUP_NAME",
          "id": "YOUR_GROUP_ID"
        }
      ]
    }
  }
}
```

Response for failure:

```json
{
  "data": {
    "userManagementRemoveUsersFromGroups": null
  },
  "errors": [
    {
      "extensions": {
        "errorClass": "SERVER_ERROR"
      },
      "locations": [
        {
          "column": 3,
          "line": 2
        }
      ],
      "message": "The following ids were not found: user_ids: 'NON-EXISTENT_USER_ID'",
      "path": [
        "userManagementRemoveUsersFromGroups"
      ]
    }
  ]
}
```

## Grant access to a group or user [#grant-access]

Access grants connect groups or users to roles and define what they can access. When you create an access grant, you're giving users or groups the permissions defined in a role, applied to a specific target (organization, accounts, entities, or other groups).

To specify who receives the access grant:

-   **For users**: Use the `grantee` parameter with `id` and `type: USER`
-   **For groups**: Replace `grantee` with `groupId: "YOUR_GROUP_ID"`

### Account-scoped grant

Here's an example of granting access to an account-scoped role:

```graphql
mutation {
  authorizationManagementGrantAccess(
    grantAccessOptions: {
      accountAccessGrants: {
        accountId: YOUR_ACCOUNT_ID
        dataAccessPolicyId: "YOUR_DATA_ACCESS_POLICY_ID"
        roleId: "YOUR_ROLE_ID"
        grantee: {
          id: "YOUR_USER_ID"
          type: USER
        }
      }
    }
  ) {
    accessGrants {
      id
    }
    roles {
      name
    }
  }
}
```

### Organization-scoped grant

Here's an example of granting access to an organization-scoped role:

```graphql
mutation {
  authorizationManagementGrantAccess(
    grantAccessOptions: {
      organizationAccessGrants: {
        roleId: "YOUR_ROLE_ID"
        grantee: {
          id: "YOUR_USER_ID"
          type: USER
        }
      }
    }
  ) {
    accessGrants {
      id
    }
    roles {
      name
    }
  }
}
```

### Entity-scoped grant

Here's an example of granting access to an entity-scoped role:

```graphql
mutation {
  authorizationManagementGrantAccess(
    grantAccessOptions: {
      entityAccessGrants: {
        entity: {
          id: "YOUR_ENTITY_ID"
          type: "YOUR_ENTITY_TYPE"
        }
        roleId: "YOUR_ROLE_ID"
        grantee: {
          id: "YOUR_USER_ID"
          type: USER
        }
      }
    }
  ) {
    accessGrants {
      id
    }
    roles {
      name
    }
  }
}
```

### Group-scoped grant

Here's an example of granting access to a group-scoped role:

```graphql
mutation {
  authorizationManagementGrantAccess(
    grantAccessOptions: {
      groupAccessGrants: {
        groupId: "YOUR_TARGET_GROUP_ID"
        roleId: "YOUR_ROLE_ID"
        grantee: {
          id: "YOUR_USER_ID"
          type: USER
        }
      }
    }
  ) {
    accessGrants {
      id
    }
    roles {
      name
    }
  }
}
```

### Response examples

Response for success:

```json
{
  "data": {
    "authorizationManagementGrantAccess": {
      "accessGrants": [
        {
          "id": "ACCESS_GRANT_ID"
        }
      ],
      "roles": [
        {
          "name": "ROLE_NAME"
        }
      ]
    }
  }
}
```

Response for failure:

```json
{
  "data": {
    "authorizationManagementGrantAccess": null
  },
  "errors": [
    {
      "extensions": {
        "errorClass": "SERVER_ERROR"
      },
      "locations": [
        {
          "column": 3,
          "line": 2
        }
      ],
      "message": "Validation failed: Role must exist, Role can't be blank, Role scope does not match granted_on type",
      "path": [
        "authorizationManagementGrantAccess"
      ]
    }
  ]
}
```

## Update access grants [#update-grants]

You can update existing account access grants to change the data access policy. Use the `authorizationManagementUpdateAccess` mutation with the grant IDs you want to update.

> #### ⚠️ IMPORTANT
>
> Updating access grants is currently only available for account-scoped grants.

Here's an example of updating an account access grant:

```graphql
mutation {
  authorizationManagementUpdateAccess(
    updateAccessOptions: {
      accountAccessGrant: {
        dataAccessPolicyId: "YOUR_NEW_DATA_ACCESS_POLICY_ID"
      }
      ids: "YOUR_ACCESS_GRANT_ID"
    }
  ) {
    grants {
      id
    }
  }
}
```

## Find a role ID [#role-id]

For some use cases, like granting access to a group, you may need a role's ID: the numeric ID representing that role in New Relic.

Here are some IDs for our default [roles](https://docs.newrelic.com/docs/accounts/accounts-billing/new-relic-one-user-management/user-management-concepts/#standard-roles) and [administration settings](https://docs.newrelic.com/docs/accounts/accounts-billing/new-relic-one-user-management/user-management-concepts/#admin-settings):

-   **All product admin**: `1254`.
-   **Standard user**: `1253`.
-   **Read only**: `1252`.
-   **Organization manager setting** `1994`
    -   **Read only**: `1995`
-   **Authentication domain setting**:
    -   **Manage**: `1996`
    -   **Read only**: `1997`
    -   **Add users**: `14517`
    -   **Read users**: `14603`
-   **Group admin**: `14516`

Here's a query for finding the ID of a custom role:

```graphql
{
  actor {
    organization {
      authorizationManagement {
        authenticationDomains(id: "YOUR_AUTHENTICATION_DOMAIN_ID") {
          authenticationDomains {
            groups {
              groups {
                displayName
                id
                roles {
                  roles {
                    roleId
                    name
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}
```

## Revoke grants from group or user [#revoke-grants]

Revoking access grants removes the connection between groups or users and roles, taking away the permissions they had. You can revoke grants at organization, account, entity, or group level. When revoking, specify who is losing access using either `grantee` (for users) or `groupId` (for groups), similar to granting access.

### Account-scoped revoke

Here's an example of revoking access to an account-scoped role:

```graphql
mutation {
  authorizationManagementRevokeAccess(
    revokeAccessOptions: {
      accountAccessGrants: {
        accountId: YOUR_ACCOUNT_ID
        dataAccessPolicyId: "YOUR_DATA_ACCESS_POLICY_ID"
        roleId: "YOUR_ROLE_ID"
        grantee: {
          id: "YOUR_USER_ID"
          type: USER
        }
      }
    }
  ) {
    accessGrants {
      id
    }
    roles {
      id
    }
  }
}
```

### Organization-scoped revoke

Here's an example of revoking access to an organization-scoped role:

```graphql
mutation {
  authorizationManagementRevokeAccess(
    revokeAccessOptions: {
      organizationAccessGrants: {
        roleId: "YOUR_ROLE_ID"
        grantee: {
          id: "YOUR_USER_ID"
          type: USER
        }
      }
    }
  ) {
    accessGrants {
      id
    }
    roles {
      id
    }
  }
}
```

### Entity-scoped revoke

Here's an example of revoking access to an entity-scoped role:

```graphql
mutation {
  authorizationManagementRevokeAccess(
    revokeAccessOptions: {
      entityAccessGrants: {
        entity: {
          id: "YOUR_ENTITY_ID"
          type: "YOUR_ENTITY_TYPE"
        }
        roleId: "YOUR_ROLE_ID"
        grantee: {
          id: "YOUR_USER_ID"
          type: USER
        }
      }
    }
  ) {
    accessGrants {
      id
    }
    roles {
      id
    }
  }
}
```

### Group-scoped revoke

Here's an example of revoking access to a group-scoped role:

```graphql
mutation {
  authorizationManagementRevokeAccess(
    revokeAccessOptions: {
      groupAccessGrants: {
        groupId: "YOUR_TARGET_GROUP_ID"
        roleId: "YOUR_ROLE_ID"
        grantee: {
          id: "YOUR_USER_ID"
          type: USER
        }
      }
    }
  ) {
    accessGrants {
      id
    }
    roles {
      id
    }
  }
}
```

### Response examples

Response for success:

```json
{
  "data": {
    "authorizationManagementRevokeAccess": {
      "accessGrants": [
        {
          "id": "ACCESS_GRANT_ID"
        }
      ],
      "roles": [
        {
          "id": "ROLE_ID"
        }
      ]
    }
  }
}
```