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

You can use our [NerdGraph API](https://docs.newrelic.com/docs/apis/nerdgraph/get-started/introduction-new-relic-nerdgraph) to view and manage users. You can add and delete users, edit your users' email address and user type, and return other types of user information.

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).

## Requirements [#requirements]

Some requirements for managing users via NerdGraph:

-   [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/#role-scopes): To view and make changes to users requires **Authentication Domain Manager** role.

## Before you start [#concepts]

Before using NerdGraph to manage users, some important points:

-   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)
-   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.
-   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).

Below are some examples of querying user information and making changes to your users.

## User type fields [#user-type]

The user type values available are:

-   `FULL_USER_TIER`
-   `CORE_USER_TIER`
-   `BASIC_USER_TIER`

## Query user information [#user-type]

Here's an example query to see all the [user types](https://docs.newrelic.com/docs/accounts/accounts-billing/new-relic-one-user-management/user-type) in your organization:

```graphql
{
  actor {
    organization {
      userManagement {
        types {
          displayName
          id
        }
      }
    }
  }
}
```

Here's an example query for getting the last active date and the user type for the users in a specific authentication domain:

```graphql
{
  actor {
    organization {
      userManagement {
        authenticationDomains (id:"AUTHENTICATION_DOMAIN_ID") {
          authenticationDomains {
            users {
              users {
                id
                name
                email
                lastActive
                type {
                  displayName
                  id
                }
              }
            }
          }
        }
      }
    }
  }
}
```

## Create users [#create-users]

The `name` field must meet [name field validation requirements](https://docs.newrelic.com/docs/accounts/accounts-billing/new-relic-one-user-management/user-management-ui-and-tasks/#name-field-requirements).

Here's an example of creating a basic user:

```graphql
mutation {
  userManagementCreateUser(
    createUserOptions: {
      authenticationDomainId: "AUTHENTICATION_DOMAIN_ID"
      email: "EMAIL_OF_USER"
      name: "NAME_OF__USER"
      userType: BASIC_USER_TIER
    }
  ) {
    createdUser {
      authenticationDomainId
      email
      id
      name
      type {
        displayName
        id
      }
    }
  }
}
```

Here's an example error response when trying to create a user within an authentication domain not set for manually provisioned users:

```json
{
  "data": {
    "userManagementCreateUser": null
  },
  "errors": [
    {
      "message": "This API can only be used to create users within Authentication Domains set for manually provisioned users."
    }
  ]
}
```

Here's an example error response when trying to create a user that already exists in an auth domain:

```json
{
  "data": {
    "userManagementCreateUser": null
  },
  "errors": [
    {
      "message": "User with email: <USER_EMAIL> and authentication domain: <AUTHENTICATION_DOMAIN_ID> already exists."
    }
  ]
}
```

## Update users [#update-users]

Here's an example of updating a user's user type to be full platform user:

```graphql
mutation {
  userManagementUpdateUser(
    updateUserOptions: { id: "ID_OF_USER", userType: FULL_USER_TIER }
  ) {
    user {
      id
      type {
        displayName
        id
      }
    }
  }
}
```

Here's an example of updating a user's email address:

```graphql
mutation {
  userManagementUpdateUser(
    updateUserOptions: { id: "ID_OF_USER", email: "EMAIL_OF_USER" }
  ) {
    user {
      id
      email
    }
  }
}
```

## Add users to groups [#groups]

For how to manage groups, and add users to groups, see [Manage user groups with NerdGraph](https://docs.newrelic.com/docs/apis/nerdgraph/examples/nerdgraph-manage-groups).

## Delete users [#delete-users]

Here's an example of deleting a user:

```graphql
mutation {
  userManagementDeleteUser(
    deleteUserOptions: { id: "ID_OF_USER" }
  ) {
    deletedUser {
      id
    }
  }
}
```

Here's an example error response when trying to delete a user in a SCIM-provisioned auth domain:

```json
{
  "data": {
    "userManagementDeleteuser": null
  },
  "errors": [
    {
      "message": "This API can only be used to delete users within Authentication Domains set for manually provisioned users."
    }
  ]
}
```

## Pagination [#pagination]

By default, the API only returns at most 500 users or 10 authentication domains. If you have more than that, you can use cursors to get the next 500 users or 10 auth domains. This call will return `nextCursor`, which can be fed into another call, using the cursor input:

```graphql
{
  actor {
    organization {
      userManagement {
        authenticationDomains(id: "AUTHENTICATION_DOMAIN_ID") {
          authenticationDomains {
            users(cursor: "=abcdEFGH2356X") {
              nextCursor
              totalCount
              users {
                email
                id
                lastActive
                name
                type {
                  displayName
                  id
                }
              }
            }
          }
        }
      }
    }
  }
}
```

Here's an example of starting a paginated return of all authentication domains for an organization:

```graphql
{
  actor {
    organization {
      userManagement {
        authenticationDomains(cursor: "=123xyzABCx") {
          nextCursor
          totalCount
          authenticationDomains {
            id
            name
          }
        }
      }
    }
  }
}
```

## Manage groups [#manage-groups]

For how to manage groups, and add and remove users from groups, see [Manage groups](https://docs.newrelic.com/docs/apis/nerdgraph/examples/nerdgraph-user-mgmt).