NerdGraph tutorial: Create and manage users

You can use our NerdGraph API 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.

Requirements

Some requirements for managing users via NerdGraph:

This is for managing users on our newer user model. Other permissions-related requirements:
- Required user type: core user or full platform user.
- Required administration settings: To view and make changes to users requires Authentication domain settings. To view and make changes at the organization level requires Organization settings.

Before you start

Before using NerdGraph to manage users, some important points:

Ensure you have a decent understanding of our user management concepts
The NerdGraph explorer has built-in docs that define the fields used in these requests.
You can track changes to your New Relic account.

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

User type fields

The user type values available are:

FULL_USER_TIER
CORE_USER_TIER
BASIC_USER_TIER

Query user information

Here's an example query to see all the user types in your organization:

{
  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:

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

Create users

Here's an example of creating a basic user:

mutation {
  userManagementCreateUser(
    createUserOptions: {
      authenticationDomainId: "YOUR_AUTH_DOMAIN_ID"
      email: "EMAIL_OF_YOUR_USER"
      name: "NAME_OF_YOUR_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:

{
  "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:

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

Update users

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

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

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

mutation {
  userManagementUpdateUser(
    updateUserOptions: { id: "ID_OF_YOUR_USER", email: "EMAIL_OF_YOUR_USER" }
  ) {
    user {
      id
      email
    }
  }
}

Add users to groups

For how to manage groups, and add users to groups, see Manage user groups with NerdGraph.

Delete users

Here's an example of deleting a user:

mutation {
  userManagementDeleteUser(deleteUserOptions: { id: "ID_OF_YOUR_USER" }) {
    deletedUser {
      id
    }
  }
}

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

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

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:

{
  actor {
    organization {
      userManagement {
        authenticationDomains(id: "YOUR_AUTH_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:

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

Manage groups

For how to manage groups, and add and remove users from groups, see Manage groups.