Skip to content

Create new role

POST/roles

Common API · Tenant role management

Create a new tenant role.

Required permissionrole:write

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.

Request body

Content type: application/json

Request body fields

namestringrequired
Role name.
Must be at most 100 characters long.
descriptionstring
Role description.
Must be at most 1000 characters long.
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.

Request samples

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


import requests

response = requests.post(
    "https://api-<data-region>.central.sophos.com/common/v1/roles",
    headers={
        "Authorization": "Bearer <access-token>",
        "X-Tenant-ID": "<tenant-id>",
        "Content-Type": "application/json",
    },
    json={   'name': 'Endpoint Admin',
    'description': 'Admin role',
    'principalType': 'user',
    '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",
  "principalType": "user",
  "permissionSets": [
    "central_admin",
    "endpoint_product_admin"
  ]
}'
Invoke-RestMethod -Method POST -Uri "https://api-<data-region>.central.sophos.com/common/v1/roles" -Headers $headers -Body $body -ContentType "application/json"


package main

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

func main() {
    req, err := http.NewRequest("POST", "https://api-<data-region>.central.sophos.com/common/v1/roles", strings.NewReader(`{
  "name": "Endpoint Admin",
  "description": "Admin role",
  "principalType": "user",
  "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", {
  method: "POST",
  headers: {
    "Authorization": "Bearer <access-token>",
    "X-Tenant-ID": "<tenant-id>",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "name": "Endpoint Admin",
  "description": "Admin role",
  "principalType": "user",
  "permissionSets": [
    "central_admin",
    "endpoint_product_admin"
  ]
}),
});
const data = await response.json();
console.log(data);

Responses

201 — Role created.

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

201

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