Skip to content

Create new role

POST/roles

Organization API · Organization role management

Create a new organization role.

Required permissionorganization-role:create

Parameters

Name In Type Required Description
X-Organization-ID header string (uuid) Yes Organization 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.central.sophos.com/organization/v1/roles" -H "Authorization: Bearer <access-token>" -H "X-Organization-ID: <organization-id>" -H "Content-Type: application/json" -d "{
  \"name\": \"Organization custom role\",
  \"description\": \"Organization custom role\",
  \"principalType\": \"user\",
  \"permissionSets\": [
    \"enterprise_admin\",
    \"endpoint_product_admin\"
  ]
}"


import requests

response = requests.post(
    "https://api.central.sophos.com/organization/v1/roles",
    headers={
        "Authorization": "Bearer <access-token>",
        "X-Organization-ID": "<organization-id>",
        "Content-Type": "application/json",
    },
    json={   'name': 'Organization custom role',
    'description': 'Organization custom role',
    'principalType': 'user',
    'permissionSets': ['enterprise_admin', 'endpoint_product_admin']},
)
print(response.json())


$headers = @{
    "Authorization" = "Bearer <access-token>"
    "X-Organization-ID" = "<organization-id>"
    "Content-Type" = "application/json"
}
$body = '{
  "name": "Organization custom role",
  "description": "Organization custom role",
  "principalType": "user",
  "permissionSets": [
    "enterprise_admin",
    "endpoint_product_admin"
  ]
}'
Invoke-RestMethod -Method POST -Uri "https://api.central.sophos.com/organization/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.central.sophos.com/organization/v1/roles", strings.NewReader(`{
  "name": "Organization custom role",
  "description": "Organization custom role",
  "principalType": "user",
  "permissionSets": [
    "enterprise_admin",
    "endpoint_product_admin"
  ]
}`))
    if err != nil {
        panic(err)
    }
    req.Header.Set("Authorization", "Bearer <access-token>")
    req.Header.Set("X-Organization-ID", "<organization-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.central.sophos.com/organization/v1/roles", {
  method: "POST",
  headers: {
    "Authorization": "Bearer <access-token>",
    "X-Organization-ID": "<organization-id>",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "name": "Organization custom role",
  "description": "Organization custom role",
  "principalType": "user",
  "permissionSets": [
    "enterprise_admin",
    "endpoint_product_admin"
  ]
}),
});
const data = await response.json();
console.log(data);

Responses

201 — Requested 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 the organization role was created.
updatedAtstring (datetime)
Date and time the organization 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"
}

See the guide for a narrative walkthrough of this API.