Skip to content

Create new role

POST/roles

Partner API · Partner role management

Create a new partner role.

Required permissionpartner-role:create

Parameters

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


import requests

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


$headers = @{
    "Authorization" = "Bearer <access-token>"
    "X-Partner-ID" = "<partner-id>"
    "Content-Type" = "application/json"
}
$body = '{
  "name": "Partner custom role",
  "description": "Partner custom role",
  "principalType": "user",
  "permissionSets": [
    "partner_admin",
    "endpoint_product_admin"
  ]
}'
Invoke-RestMethod -Method POST -Uri "https://api.central.sophos.com/partner/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/partner/v1/roles", strings.NewReader(`{
  "name": "Partner custom role",
  "description": "Partner custom role",
  "principalType": "user",
  "permissionSets": [
    "partner_admin",
    "endpoint_product_admin"
  ]
}`))
    if err != nil {
        panic(err)
    }
    req.Header.Set("Authorization", "Bearer <access-token>")
    req.Header.Set("X-Partner-ID", "<partner-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/partner/v1/roles", {
  method: "POST",
  headers: {
    "Authorization": "Bearer <access-token>",
    "X-Partner-ID": "<partner-id>",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "name": "Partner custom role",
  "description": "Partner custom role",
  "principalType": "user",
  "permissionSets": [
    "partner_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 partner role was created.
updatedAtstring (datetime)
Date and time the partner role was last updated.

Errors

Status Meaning
409 Role name already in use or is a pre-defined role name.
500 Unexpected 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.