---
title: Create custom roles for Teams
source: https://docs.newrelic.com/docs/apis/nerdgraph/examples/nerdgraph-teams-custom-role-tutorial
---

New Relic Teams lets you connect the entities you're monitoring to the teams who own them. When you can easily see who owns an entity, you can speed up troubleshooting, enhance team collaboration, and improve your operational efficiency.

## Default Teams access [#default-access]

New Relic provides default access to Teams through these standard roles:

| Action                  | Required role                                                                                                                                                                                                                                                                                                                |
| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| View teams              | [**Organization read only**](https://docs.newrelic.com/docs/accounts/accounts-billing/new-relic-one-user-management/user-management-concepts/#standard-roles)                                                                                                                                                                |
| Modify teams            | [**Organization Product Admin**](https://docs.newrelic.com/docs/accounts/accounts-billing/new-relic-one-user-management/user-management-concepts/#standard-roles)                                                                                                                                                            |
| Create and delete teams | [**Organization Manager**](https://docs.newrelic.com/docs/accounts/accounts-billing/new-relic-one-user-management/user-management-concepts/#standard-roles) or [**Authentication Manager**](https://docs.newrelic.com/docs/accounts/accounts-billing/new-relic-one-user-management/user-management-concepts/#standard-roles) |

You might need a custom role if the default permissions don't meet your organization's needs.

## Teams capabilities [#capabilities]

When building a custom role for Teams, use the permissions below. Teams permissions are organization-scoped.

| Capability                                            | Permission identifier                |
| ----------------------------------------------------- | ------------------------------------ |
| Read teams                                            | `teams.read.team`                    |
| Delete teams                                          | `teams.delete.team`                  |
| Create teams                                          | `teams.create.team`                  |
| Modify teams                                          | `teams.update.team`                  |
| Read access to the automations/settings page          | `teams.read.organization_settings`   |
| Modify access to the automations/settings page        | `teams.manage.organization_settings` |
| Create teams from IdP user groups (for example, Okta) | `authentication_domain.read.groups`  |

## Prerequisites [#prerequisites]

Before you begin, ensure you have:

-   [General NerdGraph requirements](https://docs.newrelic.com/docs/apis/nerdgraph/get-started/introduction-new-relic-nerdgraph/#authentication)
-   Organization Admin with `Authentication Domain Manager` role to create custom roles

> #### 💡 TIP
>
> You can also create a custom role for Teams through the UI. For the permissions to select and the scope to use, see [Teams capabilities](https://docs.newrelic.com/docs/service-architecture-intelligence/teams/teams/#teams-capabilities).

To create a custom role via the NerdGraph API, perform the following steps:

## Find the required permission IDs for Teams

Use the `customerAdministration` query to retrieve a list of capabilities, their permission IDs, and related information. Filter by `scope: "organization"` to get Teams permissions.

#### Input parameters

| Parameter | Data Type | Is it Required? | Description                                                        |
| --------- | --------- | --------------- | ------------------------------------------------------------------ |
| `eq`      | String    | Yes             | Set the value to `organization` to retrieve permissions for Teams. |

#### Sample request

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

#### Sample response

```json
{
  "data": {
    "customerAdministration": {
      "permissions": {
        "items": [
          {
            "category": "READ",
            "feature": "Teams",
            "id": "xxxxx",
            "product": "New Relic One"
          },
          {
            "category": "OTHER",
            "feature": "Teams",
            "id": "xxxxxx",
            "product": "New Relic One"
          },
          {
            "category": "DELETE",
            "feature": "Teams",
            "id": "xxxxx",
            "product": "New Relic One"
          },
          {
            "category": "MODIFY",
            "feature": "Teams",
            "id": "xxxxxx",
            "product": "New Relic One"
          }
        ]
      }
    }
  }
}
```

From the response, identify and copy the permission IDs where `feature` is `"Teams"` and the `category` matches the access level you want to grant. You'll need these IDs in the next step.

````

## Retrieve your organization ID

Retrieve your organization ID, which you'll use in subsequent mutations.

#### Sample request

````graphql
{
  actor {
    organization {
      id
    }
  }
}
```

#### Sample response

```json
{
  "data": {
    "actor": {
      "organization": {
        "id": "YOUR_ORGANIZATION_ID"
      }
    }
  }
}
```

Copy your organization ID from the response. You'll need it to create the custom role.

````

## Create the custom role

Use the `customRoleCreate` mutation to create your custom role for Teams management.

#### Input parameters

| Parameter       | Data Type         | Is it Required? | Description                                    |
| --------------- | ----------------- | --------------- | ---------------------------------------------- |
| `id`            | String            | Yes             | The organization ID from the previous step.    |
| `type`          | String            | Yes             | Set to `organization`.                         |
| `name`          | String            | Yes             | The display name for the custom role.          |
| `permissionIds` | Array of Integers | Yes             | The Teams permission IDs identified in Step 1. |
| `scope`         | String            | Yes             | Set to `organization`.                         |

#### Sample request

````graphql
mutation {
  customRoleCreate(
    container: {
      id: "YOUR_ORGANIZATION_ID"
      type: "organization"
    }
    name: "Teams manager"
    permissionIds: [xxxxx, xxxxx]
    scope: "organization"
  ) {
    id
  }
}
```

#### Sample response

```json
{
  "data": {
    "customRoleCreate": {
      "id": 9999999
    }
  }
}
```

Save the returned role ID — you'll need it to assign this role to a user group.

````

## Add the custom role to a user group

After creating the custom role, assign it to a user group in New Relic.

### Retrieve group IDs

Use the `customerAdministration` query to get a list of available user groups.

#### Input parameters

| Parameter | Data Type | Is it Required? | Description                                 |
| --------- | --------- | --------------- | ------------------------------------------- |
| `id`      | String    | Yes             | The organization ID from the previous step. |

#### Sample request

````graphql
{
  customerAdministration {
    groups(
      filter: {
        organizationId: { eq: "YOUR_ORGANIZATION_ID" }
      }
    ) {
      nextCursor
      items {
        id
        name
        users {
          items {
            id
            email
          }
        }
      }
    }
  }
}
```

From the response, copy the group ID for the group you want to assign the Teams role to.

### Assign the role to the group

Use the `authorizationManagementGrantAccess` mutation to assign the custom role to a user group.

#### Input parameters

<table>
  <thead>
    <tr>
      <th>Parameter</th>
      <th>Data Type</th>
      <th>Is it Required?</th>
      <th>Description</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>`roleId`</td>
      <td>String</td>
      <td>Yes</td>
      <td>The custom role ID from the previous step.</td>
    </tr>
    <tr>
      <td>`groupId`</td>
      <td>String</td>
      <td>Yes</td>
      <td>The group ID retrieved above.</td>
    </tr>
  </tbody>
</table>

#### Sample request

```graphql
mutation {
  authorizationManagementGrantAccess(
    grantAccessOptions: {
      organizationAccessGrants: { roleId: "YOUR_ROLE_ID" }
      groupId: "YOUR_GROUP_ID"
    }
  ) {
    roles {
      id
      name
      organizationId
      roleId
      groupId
      displayName
    }
  }
}
```

#### Sample response

```json
{
  "data": {
    "authorizationManagementGrantAccess": {
      "roles": [
        {
          "displayName": "Teams manager",
          "groupId": null,
          "id": "99999999",
          "name": "teams_manager",
          "organizationId": "YOUR_ORGANIZATION_ID",
          "roleId": 99999
        }
      ]
    }
  }
}
```

````

## Manage existing custom roles [#manage-roles]

**Update a role**

Use the `customRoleUpdate` mutation to rename a role or replace its permission set.

````graphql
mutation {
  customRoleUpdate(
    id: ROLE_ID
    name: "Updated role name"
    permissionIds: [xxxxx, xxxxx]
  ) {
    id
  }
}
```

<table>
  <thead>
    <tr>
      <th>Parameter</th>
      <th>Description</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>`id`</td>
      <td>The ID of the role to update.</td>
    </tr>
    <tr>
      <td>`name`</td>
      <td>New display name for the role.</td>
    </tr>
    <tr>
      <td>`permissionIds`</td>
      <td>Full replacement list of permission IDs. This replaces all existing permissions on the role.</td>
    </tr>
  </tbody>
</table>

````

**Delete a role**

Use the `customRoleDelete` mutation to permanently remove a custom role.

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

The response returns the ID of the deleted role, confirming successful deletion.

````

**Find a custom role's ID**

Use the following query to look up a role ID by browsing your organization's groups and their assigned roles.

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

````

For more information about Teams, see the [Teams documentation](https://docs.newrelic.com/docs/service-architecture-intelligence/teams/teams/).