For AI agents: A markdown version of this page is available at https://docs.datadoghq.com/api/latest/roles/update-a-role.md. A documentation index is available at /llms.txt.

Update a role

PATCH https://api.ap1.datadoghq.com/api/v2/roles/{role_id}https://api.ap2.datadoghq.com/api/v2/roles/{role_id}https://api.datadoghq.eu/api/v2/roles/{role_id}https://api.ddog-gov.com/api/v2/roles/{role_id}https://api.us2.ddog-gov.com/api/v2/roles/{role_id}https://api.uk1.datadoghq.com/api/v2/roles/{role_id}https://api.datadoghq.com/api/v2/roles/{role_id}https://api.us3.datadoghq.com/api/v2/roles/{role_id}https://api.us5.datadoghq.com/api/v2/roles/{role_id}

Overview

Edit a role. Can only be used with application keys belonging to administrators.

Restricted permissions, such as Dashboards Read and Monitors Read, remain on the role by default, even if they are omitted from the request. To exclude them, set default_permissions_opt_out to true.

This endpoint requires the user_access_manage permission.

OAuth apps require the user_access_manage authorization scope to access this endpoint.

Arguments

Path Parameters

Name

Type

Description

role_id [required]

string

The unique identifier of the role.

Request

Body Data (required)

Expand All

Field

Type

Description

data [required]

object

Data related to the update of a role.

attributes [required]

object

Attributes of the role.

created_at

date-time

Creation time of the role.

default_permissions_opt_out

boolean

Whether to exclude restricted default permissions from this role. Restricted default permissions are automatically assigned to every role by default. Set this field to true to exclude them. Some of these permissions can only be excluded after Minimal Access Roles is enabled for the organization.

modified_at

date-time

Time of last role modification.

name

string

Name of the role.

receives_permissions_from

[string]

The managed role from which this role automatically inherits new permissions. Specify one of the following: "Datadog Admin Role", "Datadog Standard Role", or "Datadog Read Only Role". If empty or not specified, the role does not automatically inherit permissions from any managed role.

user_count

int32

The user count.

id [required]

string

The unique identifier of the role.

relationships

object

Relationships of the role object.

permissions

object

Relationship to multiple permissions objects.

data

[object]

Relationships to permission objects.

id

string

ID of the permission.

type

enum

Permissions resource type. Allowed enum values: permissions

default: permissions

type [required]

enum

Roles type. Allowed enum values: roles

default: roles

{
  "data": {
    "id": "string",
    "type": "roles",
    "attributes": {
      "name": "developers-updated"
    },
    "relationships": {
      "permissions": {
        "data": [
          {
            "id": "f2a8beb4-91f8-962d-b6d9-60215cda2214",
            "type": "permissions"
          }
        ]
      }
    }
  }
}

Response

OK

Response containing information about an updated role.

Expand All

Field

Type

Description

data

object

Role object returned by the API.

attributes

object

Attributes of the role.

created_at

date-time

Creation time of the role.

default_permissions_opt_out

boolean

Whether to exclude restricted default permissions from this role. Restricted default permissions are automatically assigned to every role by default. Set this field to true to exclude them. Some of these permissions can only be excluded after Minimal Access Roles is enabled for the organization.

modified_at

date-time

Time of last role modification.

name

string

Name of the role.

receives_permissions_from

[string]

The managed role from which this role automatically inherits new permissions. Specify one of the following: "Datadog Admin Role", "Datadog Standard Role", or "Datadog Read Only Role". If empty or not specified, the role does not automatically inherit permissions from any managed role.

user_count

int32

The user count.

id

string

The unique identifier of the role.

relationships

object

Relationships of the role object returned by the API.

permissions

object

Relationship to multiple permissions objects.

data

[object]

Relationships to permission objects.

id

string

ID of the permission.

type

enum

Permissions resource type. Allowed enum values: permissions

default: permissions

type [required]

enum

Roles type. Allowed enum values: roles

default: roles

{
  "data": {
    "attributes": {
      "created_at": "2019-09-19T10:00:00.000Z",
      "default_permissions_opt_out": false,
      "modified_at": "2019-09-19T10:00:00.000Z",
      "name": "string",
      "receives_permissions_from": [],
      "user_count": "integer"
    },
    "id": "string",
    "relationships": {
      "permissions": {
        "data": [
          {
            "id": "string",
            "type": "permissions"
          }
        ]
      }
    },
    "type": "roles"
  }
}

Bad Request

API error response.

Expand All

Field

Type

Description

errors [required]

[string]

A list of errors.

{
  "errors": [
    "Bad Request"
  ]
}

Authentication error

API error response.

Expand All

Field

Type

Description

errors [required]

[string]

A list of errors.

{
  "errors": [
    "Bad Request"
  ]
}

Not found

API error response.

Expand All

Field

Type

Description

errors [required]

[string]

A list of errors.

{
  "errors": [
    "Bad Request"
  ]
}

Unprocessable Entity

API error response.

Expand All

Field

Type

Description

errors [required]

[string]

A list of errors.

{
  "errors": [
    "Bad Request"
  ]
}

Too many requests

API error response.

Expand All

Field

Type

Description

errors [required]

[string]

A list of errors.

{
  "errors": [
    "Bad Request"
  ]
}

Code Example

                  ## default
# 

# Path parameters
export role_id="CHANGE_ME"
# Use a Personal Access Token or Service Access Token
export DD_BEARER_TOKEN="<PERSONAL_ACCESS_TOKEN OR SERVICE_ACCESS_TOKEN>"

# Curl command
curl -X PATCH "https://api.ap1.datadoghq.com"https://api.ap2.datadoghq.com"https://api.datadoghq.eu"https://api.ddog-gov.com"https://api.us2.ddog-gov.com"https://api.uk1.datadoghq.com"https://api.datadoghq.com"https://api.us3.datadoghq.com"https://api.us5.datadoghq.com/api/v2/roles/${role_id}" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer ${DD_BEARER_TOKEN}" \ -d @- << EOF { "data": { "attributes": { "name": "updated-role-name" }, "id": "00000000-0000-1111-0000-000000000000", "type": "roles" } } EOF
"""
Update a role returns "OK" response
"""

from os import environ
from datadog_api_client import ApiClient, Configuration
from datadog_api_client.v2.api.roles_api import RolesApi
from datadog_api_client.v2.model.permissions_type import PermissionsType
from datadog_api_client.v2.model.relationship_to_permission_data import RelationshipToPermissionData
from datadog_api_client.v2.model.relationship_to_permissions import RelationshipToPermissions
from datadog_api_client.v2.model.role_relationships import RoleRelationships
from datadog_api_client.v2.model.role_update_attributes import RoleUpdateAttributes
from datadog_api_client.v2.model.role_update_data import RoleUpdateData
from datadog_api_client.v2.model.role_update_request import RoleUpdateRequest
from datadog_api_client.v2.model.roles_type import RolesType

# there is a valid "role" in the system
ROLE_DATA_ATTRIBUTES_NAME = environ["ROLE_DATA_ATTRIBUTES_NAME"]
ROLE_DATA_ID = environ["ROLE_DATA_ID"]

# there is a valid "permission" in the system
PERMISSION_ID = environ["PERMISSION_ID"]

body = RoleUpdateRequest(
    data=RoleUpdateData(
        id=ROLE_DATA_ID,
        type=RolesType.ROLES,
        attributes=RoleUpdateAttributes(
            name="developers-updated",
        ),
        relationships=RoleRelationships(
            permissions=RelationshipToPermissions(
                data=[
                    RelationshipToPermissionData(
                        id=PERMISSION_ID,
                        type=PermissionsType.PERMISSIONS,
                    ),
                ],
            ),
        ),
    ),
)

configuration = Configuration()
configuration.access_token = environ["DD_BEARER_TOKEN"]
with ApiClient(configuration) as api_client:
    api_instance = RolesApi(api_client)
    response = api_instance.update_role(role_id=ROLE_DATA_ID, body=body)

    print(response)

Instructions

First install the library and its dependencies and then save the example to example.py and run following commands:

    
DD_SITE="datadoghq.comus3.datadoghq.comus5.datadoghq.comdatadoghq.euap1.datadoghq.comap2.datadoghq.comuk1.datadoghq.comddog-gov.comus2.ddog-gov.com" DD_BEARER_TOKEN="<PERSONAL_ACCESS_TOKEN OR SERVICE_ACCESS_TOKEN>" python3 "example.py"
# Update a role returns "OK" response

require "datadog_api_client"
DatadogAPIClient.configure do |config|
  config.access_token = ENV["DD_BEARER_TOKEN"]
end
api_instance = DatadogAPIClient::V2::RolesAPI.new

# there is a valid "role" in the system
ROLE_DATA_ATTRIBUTES_NAME = ENV["ROLE_DATA_ATTRIBUTES_NAME"]
ROLE_DATA_ID = ENV["ROLE_DATA_ID"]

# there is a valid "permission" in the system
PERMISSION_ID = ENV["PERMISSION_ID"]

body = DatadogAPIClient::V2::RoleUpdateRequest.new({
  data: DatadogAPIClient::V2::RoleUpdateData.new({
    id: ROLE_DATA_ID,
    type: DatadogAPIClient::V2::RolesType::ROLES,
    attributes: DatadogAPIClient::V2::RoleUpdateAttributes.new({
      name: "developers-updated",
    }),
    relationships: DatadogAPIClient::V2::RoleRelationships.new({
      permissions: DatadogAPIClient::V2::RelationshipToPermissions.new({
        data: [
          DatadogAPIClient::V2::RelationshipToPermissionData.new({
            id: PERMISSION_ID,
            type: DatadogAPIClient::V2::PermissionsType::PERMISSIONS,
          }),
        ],
      }),
    }),
  }),
})
p api_instance.update_role(ROLE_DATA_ID, body)

Instructions

First install the library and its dependencies and then save the example to example.rb and run following commands:

    
DD_SITE="datadoghq.comus3.datadoghq.comus5.datadoghq.comdatadoghq.euap1.datadoghq.comap2.datadoghq.comuk1.datadoghq.comddog-gov.comus2.ddog-gov.com" DD_BEARER_TOKEN="<PERSONAL_ACCESS_TOKEN OR SERVICE_ACCESS_TOKEN>" rb "example.rb"
// Update a role returns "OK" response

import com.datadog.api.client.ApiClient;
import com.datadog.api.client.ApiException;
import com.datadog.api.client.v2.api.RolesApi;
import com.datadog.api.client.v2.model.PermissionsType;
import com.datadog.api.client.v2.model.RelationshipToPermissionData;
import com.datadog.api.client.v2.model.RelationshipToPermissions;
import com.datadog.api.client.v2.model.RoleRelationships;
import com.datadog.api.client.v2.model.RoleUpdateAttributes;
import com.datadog.api.client.v2.model.RoleUpdateData;
import com.datadog.api.client.v2.model.RoleUpdateRequest;
import com.datadog.api.client.v2.model.RoleUpdateResponse;
import com.datadog.api.client.v2.model.RolesType;
import java.util.Collections;

public class Example {
  public static void main(String[] args) {
    ApiClient defaultClient = ApiClient.getDefaultApiClient();
    defaultClient.setAccessToken(System.getenv("DD_BEARER_TOKEN"));
    RolesApi apiInstance = new RolesApi(defaultClient);

    // there is a valid "role" in the system
    String ROLE_DATA_ATTRIBUTES_NAME = System.getenv("ROLE_DATA_ATTRIBUTES_NAME");
    String ROLE_DATA_ID = System.getenv("ROLE_DATA_ID");

    // there is a valid "permission" in the system
    String PERMISSION_ID = System.getenv("PERMISSION_ID");

    RoleUpdateRequest body =
        new RoleUpdateRequest()
            .data(
                new RoleUpdateData()
                    .id(ROLE_DATA_ID)
                    .type(RolesType.ROLES)
                    .attributes(new RoleUpdateAttributes().name("developers-updated"))
                    .relationships(
                        new RoleRelationships()
                            .permissions(
                                new RelationshipToPermissions()
                                    .data(
                                        Collections.singletonList(
                                            new RelationshipToPermissionData()
                                                .id(PERMISSION_ID)
                                                .type(PermissionsType.PERMISSIONS))))));

    try {
      RoleUpdateResponse result = apiInstance.updateRole(ROLE_DATA_ID, body);
      System.out.println(result);
    } catch (ApiException e) {
      System.err.println("Exception when calling RolesApi#updateRole");
      System.err.println("Status code: " + e.getCode());
      System.err.println("Reason: " + e.getResponseBody());
      System.err.println("Response headers: " + e.getResponseHeaders());
      e.printStackTrace();
    }
  }
}

Instructions

First install the library and its dependencies and then save the example to Example.java and run following commands:

    
DD_SITE="datadoghq.comus3.datadoghq.comus5.datadoghq.comdatadoghq.euap1.datadoghq.comap2.datadoghq.comuk1.datadoghq.comddog-gov.comus2.ddog-gov.com" DD_BEARER_TOKEN="<PERSONAL_ACCESS_TOKEN OR SERVICE_ACCESS_TOKEN>" java "Example.java"
// Update a role returns "OK" response
use datadog_api_client::datadog;
use datadog_api_client::datadogV2::api_roles::RolesAPI;
use datadog_api_client::datadogV2::model::PermissionsType;
use datadog_api_client::datadogV2::model::RelationshipToPermissionData;
use datadog_api_client::datadogV2::model::RelationshipToPermissions;
use datadog_api_client::datadogV2::model::RoleRelationships;
use datadog_api_client::datadogV2::model::RoleUpdateAttributes;
use datadog_api_client::datadogV2::model::RoleUpdateData;
use datadog_api_client::datadogV2::model::RoleUpdateRequest;
use datadog_api_client::datadogV2::model::RolesType;

#[tokio::main]
async fn main() {
    // there is a valid "role" in the system
    let role_data_id = std::env::var("ROLE_DATA_ID").unwrap();

    // there is a valid "permission" in the system
    let permission_id = std::env::var("PERMISSION_ID").unwrap();
    let body = RoleUpdateRequest::new(
        RoleUpdateData::new(
            RoleUpdateAttributes::new().name("developers-updated".to_string()),
            role_data_id.clone(),
            RolesType::ROLES,
        )
        .relationships(RoleRelationships::new().permissions(
            RelationshipToPermissions::new().data(vec![
                            RelationshipToPermissionData::new()
                                .id(permission_id.clone())
                                .type_(PermissionsType::PERMISSIONS)
                        ]),
        )),
    );
    let configuration = datadog::Configuration::new();
    let api = RolesAPI::with_config(configuration);
    let resp = api.update_role(role_data_id.clone(), body).await;
    if let Ok(value) = resp {
        println!("{:#?}", value);
    } else {
        println!("{:#?}", resp.unwrap_err());
    }
}

Instructions

First install the library and its dependencies and then save the example to src/main.rs and run following commands:

    
DD_SITE="datadoghq.comus3.datadoghq.comus5.datadoghq.comdatadoghq.euap1.datadoghq.comap2.datadoghq.comuk1.datadoghq.comddog-gov.comus2.ddog-gov.com" DD_API_KEY="<DD_API_KEY>" DD_APP_KEY="<DD_APP_KEY>" cargo run
/**
 * Update a role returns "OK" response
 */

import { client, v2 } from "@datadog/datadog-api-client";

const configuration = client.createConfiguration({
  authMethods: {
    AuthZ: {
      accessToken: process.env.DD_BEARER_TOKEN as string,
    },
  },
});
const apiInstance = new v2.RolesApi(configuration);

// there is a valid "role" in the system
const ROLE_DATA_ID = process.env.ROLE_DATA_ID as string;

// there is a valid "permission" in the system
const PERMISSION_ID = process.env.PERMISSION_ID as string;

const params: v2.RolesApiUpdateRoleRequest = {
  body: {
    data: {
      id: ROLE_DATA_ID,
      type: "roles",
      attributes: {
        name: "developers-updated",
      },
      relationships: {
        permissions: {
          data: [
            {
              id: PERMISSION_ID,
              type: "permissions",
            },
          ],
        },
      },
    },
  },
  roleId: ROLE_DATA_ID,
};

apiInstance
  .updateRole(params)
  .then((data: v2.RoleUpdateResponse) => {
    console.log(
      "API called successfully. Returned data: " + JSON.stringify(data)
    );
  })
  .catch((error: any) => console.error(error));

Instructions

First install the library and its dependencies and then save the example to example.ts and run following commands:

    
DD_SITE="datadoghq.comus3.datadoghq.comus5.datadoghq.comdatadoghq.euap1.datadoghq.comap2.datadoghq.comuk1.datadoghq.comddog-gov.comus2.ddog-gov.com" DD_BEARER_TOKEN="<PERSONAL_ACCESS_TOKEN OR SERVICE_ACCESS_TOKEN>" tsc "example.ts"
// Update a role returns "OK" response

package main

import (
	"context"
	"encoding/json"
	"fmt"
	"os"

	"github.com/DataDog/datadog-api-client-go/v2/api/datadog"
	"github.com/DataDog/datadog-api-client-go/v2/api/datadogV2"
)

func main() {
	// there is a valid "role" in the system
	RoleDataID := os.Getenv("ROLE_DATA_ID")

	// there is a valid "permission" in the system
	PermissionID := os.Getenv("PERMISSION_ID")

	body := datadogV2.RoleUpdateRequest{
		Data: datadogV2.RoleUpdateData{
			Id:   RoleDataID,
			Type: datadogV2.ROLESTYPE_ROLES,
			Attributes: datadogV2.RoleUpdateAttributes{
				Name: datadog.PtrString("developers-updated"),
			},
			Relationships: &datadogV2.RoleRelationships{
				Permissions: &datadogV2.RelationshipToPermissions{
					Data: []datadogV2.RelationshipToPermissionData{
						{
							Id:   datadog.PtrString(PermissionID),
							Type: datadogV2.PERMISSIONSTYPE_PERMISSIONS.Ptr(),
						},
					},
				},
			},
		},
	}
	ctx := datadog.NewDefaultContext(context.Background())
	ctx = context.WithValue(ctx, datadog.ContextAccessToken, os.Getenv("DD_BEARER_TOKEN"))
	configuration := datadog.NewConfiguration()
	apiClient := datadog.NewAPIClient(configuration)
	api := datadogV2.NewRolesApi(apiClient)
	resp, r, err := api.UpdateRole(ctx, RoleDataID, body)

	if err != nil {
		fmt.Fprintf(os.Stderr, "Error when calling `RolesApi.UpdateRole`: %v\n", err)
		fmt.Fprintf(os.Stderr, "Full HTTP response: %v\n", r)
	}

	responseContent, _ := json.MarshalIndent(resp, "", "  ")
	fmt.Fprintf(os.Stdout, "Response from `RolesApi.UpdateRole`:\n%s\n", responseContent)
}

Instructions

First install the library and its dependencies and then save the example to main.go and run following commands:

    
DD_SITE="datadoghq.comus3.datadoghq.comus5.datadoghq.comdatadoghq.euap1.datadoghq.comap2.datadoghq.comuk1.datadoghq.comddog-gov.comus2.ddog-gov.com" DD_BEARER_TOKEN="<PERSONAL_ACCESS_TOKEN OR SERVICE_ACCESS_TOKEN>" go run "main.go"