Skip to content

Patch role

PATCH/roles/{roleId}

Common API · Tenant role management

Patch an existing tenant role.

Required permissionrole:update

Parameters

Name In Type Required Description
X-Tenant-ID header string (uuid) Yes Tenant ID.
fields query array of string No The fields to return in a partial response.
roleId path string (uuid) Yes Role ID.

Request body

Content type: application/json

Request body fields

namestring
Role name.
Must be at most 100 characters long.
descriptionstring
Role description.
Must be at most 1000 characters long.
permissionSetsOption 1 or Option 2
Permission sets to be updated.

Option 1

Set of permissions to operate on.
Show child attributesHide child attributes
permissionSetsarray of string
Set of permissions to operate on.
Items must be unique.

Option 2

Update permission set by adding or removing permissions.
Show child attributesHide child attributes
addarray of string
Permissions to add.
Items must be unique.
removearray of string
Permissions to remove.
Items must be unique.

Request samples

curl -X PATCH "https://api-<data-region>.central.sophos.com/common/v1/roles/<roleId>" -H "Authorization: Bearer <access-token>" -H "X-Tenant-ID: <tenant-id>" -H "Content-Type: application/json" -d "{
  \"name\": \"Endpoint Admin\",
  \"description\": \"Admin role\",
  \"permissionSets\": [
    \"central_admin\",
    \"endpoint_product_admin\"
  ]
}"


import requests

response = requests.patch(
    "https://api-<data-region>.central.sophos.com/common/v1/roles/<roleId>",
    headers={
        "Authorization": "Bearer <access-token>",
        "X-Tenant-ID": "<tenant-id>",
        "Content-Type": "application/json",
    },
    json={   'name': 'Endpoint Admin',
    'description': 'Admin role',
    'permissionSets': ['central_admin', 'endpoint_product_admin']},
)
print(response.json())


$headers = @{
    "Authorization" = "Bearer <access-token>"
    "X-Tenant-ID" = "<tenant-id>"
    "Content-Type" = "application/json"
}
$body = '{
  "name": "Endpoint Admin",
  "description": "Admin role",
  "permissionSets": [
    "central_admin",
    "endpoint_product_admin"
  ]
}'
Invoke-RestMethod -Method PATCH -Uri "https://api-<data-region>.central.sophos.com/common/v1/roles/<roleId>" -Headers $headers -Body $body -ContentType "application/json"


package main

import (
    "fmt"
    "io"
    "net/http"
    "strings"
)

func main() {
    req, err := http.NewRequest("PATCH", "https://api-<data-region>.central.sophos.com/common/v1/roles/<roleId>", strings.NewReader(`{
  "name": "Endpoint Admin",
  "description": "Admin role",
  "permissionSets": [
    "central_admin",
    "endpoint_product_admin"
  ]
}`))
    if err != nil {
        panic(err)
    }
    req.Header.Set("Authorization", "Bearer <access-token>")
    req.Header.Set("X-Tenant-ID", "<tenant-id>")
    req.Header.Set("Content-Type", "application/json")

    resp, err := http.DefaultClient.Do(req)
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()

    body, _ := io.ReadAll(resp.Body)
    fmt.Println(string(body))
}


const response = await fetch("https://api-<data-region>.central.sophos.com/common/v1/roles/<roleId>", {
  method: "PATCH",
  headers: {
    "Authorization": "Bearer <access-token>",
    "X-Tenant-ID": "<tenant-id>",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "name": "Endpoint Admin",
  "description": "Admin role",
  "permissionSets": [
    "central_admin",
    "endpoint_product_admin"
  ]
}),
});
const data = await response.json();
console.log(data);

Responses

200 — Updated role.

Response fields

idstring (uuid)required
Role UUID.
namestringrequired
Role name.
descriptionstring
Role Description.
typestring (enum)required
Role type.
Must be one of: predefined, custom.
principalTypestring (enum)required
Principal type of role.
Must be one of: user, service.
permissionSetsarray of stringrequired
List of permission sets.
Must contain at least 1 item. Items must be unique.
createdAtstring (datetime)
Date and time tenant role was created.
updatedAtstring (datetime)
Date and time tenant role was last updated.

Errors

Status Meaning
404 Role not found with given ID.
409 Role name already in use or is a pre-defined role name.
500 Internal server error.

All error responses share the same shape — see the error response object.

Response examples

200

{
  "id": "00000000-0000-0000-0000-000000000000",
  "name": "string",
  "description": "string",
  "type": "predefined",
  "principalType": "user",
  "permissionSets": [
    "string"
  ],
  "createdAt": "string",
  "updatedAt": "string"
}