NerdGraph tutorial: Manage user groups

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

To use NerdGraph to create users, and view their information, see Manage users with NerdGraph.

Requirements

Some requirements for managing users and groups via NerdGraph:

Before you start

Before using NerdGraph to manage users:

Suggested workflow for creating groups

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 and available 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: 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: 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 region New Relic accounts, 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.

Query groups

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

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

Query existing roles

Here's an example of returning information about roles:

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

Here's an example result:

{
"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 user information

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

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

Here's an example result:

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

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

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

Here's an example response:

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

Create a role

Here's an example of creating a role:

mutation {
customRoleCreate(
container: { id: "$YOUR_ORGANIZATION_ID", type: "ORGANIZATION" }
name: "MY CUSTOM ROLE"
permissionIds: [1, 2, 3]
scope: "ACCOUNT"
) {
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. Example: "MY CUSTOM ROLE".
  • permissionIds: (Array) A list of permission IDs representing the capabilities assigned to the custom role. Ensure these IDs correspond to valid permissions in your system.
  • scope: (String) The level at which the role's permissions apply. In this instance, the scope is "ACCOUNT".

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.
    • Ensure that the permissionIds provided are valid and align with the permissions you want to grant.

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

Use the following query to retrieve the list of permissions:

mutation {
customerAdministration {
permissions {
items {
category
feature
id
product
subsetIds
}
nextCursor
}
}
}

This returns account-scoped permissions. For permissions scoped to an org, run the following query instead:

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

After you have the unique identifier for each permission you want to assign to the new role, create that role.

Update role

Here's an example of updating a role.

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

Here's an example of deleting a role:

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

Here's an example of creating a group:

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

Successful response:

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

Update user group

Here's an example of updating a group.

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

Response for success:

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

Response for failure:

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

Delete a group

Here's an example of deleting a group:

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

Response for success:

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

Response for failure:

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

Here's an example of adding users to groups:

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

Response for success:

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

Response for failure:

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

Here's an example of removing users from groups:

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

Response for success:

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

Response for failure:

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

Here's an example of granting a group access to a role and an account:

mutation {
authorizationManagementGrantAccess(
grantAccessOptions: {
groupId: "YOUR_GROUP_ID"
accountAccessGrants: {
accountId: YOUR_ACCOUNT_ID
roleId: "YOUR_ROLE_ID"
}
}
) {
roles {
displayName
accountId
}
}
}

Response for success:

{
"data": {
"authorizationManagementGrantAccess": {
"roles": [
{
"displayName": "ROLE_NAME_1",
"id": "ROLE_ID_1"
},
{
"displayName": "ROLE_NAME_2",
"id": "ROLE_ID_2"
},
{
"displayName": "ROLE_NAME_3",
"id": "ROLE_ID_3"
},
{
"displayName": "ROLE_NAME_4",
"id": "ROLE_ID_4"
}
]
}
}
}

Response for failure:

{
"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"]
}
]
}

Find a 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 and administration 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:

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

Revoke grants from group

Here's an example of removing access from a group:

mutation {
authorizationManagementRevokeAccess(
revokeAccessOptions: {
accountAccessGrants: {
accountId: YOUR_ACCOUNT_ID
roleId: "YOUR_ROLE_ID"
}
groupId: "YOUR_GROUP_ID"
}
) {
roles {
accountId
displayName
}
}
}

Response for success:

{
"data": {
"authorizationManagementRevokeAccess": {
"roles": [
{
"displayName": "ROLE_NAME_1",
"id": "ROLE_ID_1"
},
{
"displayName": "ROLE_NAME_2",
"id": "ROLE_ID_2"
},
{
"displayName": "ROLE_NAME_3",
"id": "ROLE_ID_3"
}
]
}
}
}