Create role

Creates a role and sets which features it can use.

POST /fieldservicegateway/usermanagement/v3/authorization/create-role

Request

Field	Type	Required	Description
roleName	string	yes	Application:RoleName, for example Honeycomb:Read
isTechnicianRole	boolean	yes	true when people with this role are technicians
roleType	string	no	SA for a service administrator role, or SP for a service provider role
assignFeatures	string[]	no	Features to grant. Each item is module:level or module/feature:level
unassignFeatures	string[]	no	Features to remove, in the same form
serviceProviderNumber	string	for a custom role	When set, the role belongs to this service provider. Required for ServiceBenchElite

Example

{
  "roleName": "Honeycomb:Read",
  "isTechnicianRole": false,
  "roleType": "SP",
  "assignFeatures": ["jobmanagement:Read"]
}

cURL

curl --request POST 'https://[BASE_URL]/fieldservicegateway/usermanagement/v3/authorization/create-role' \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: {{x-api-key}}' \
  --header 'Authorization: {{Authorization}}' \
  --header 'Asurion-correlationid: correlation-id' \
  --header 'Asurion-enduser: end-user' \
  --header 'Asurion-sourcesystem: source-system' \
  --header 'Asurion-serviceprovider: company-id' \
  --header 'Asurion-client: default' \
  --data '{
    "roleName": "Honeycomb:Read",
    "isTechnicianRole": false,
    "roleType": "SP",
    "assignFeatures": ["jobmanagement:Read"]
  }'

Response

201 Created

{
  "success": true,
  "message": "Role definition processed successfully — 1 tuple(s) inserted",
  "data": {
    "tupleCount": 1,
    "tuples": []
  }
}

Field	Type	Description
success	boolean	true when the role was saved
message	string	What changed. If nothing changed, the message says the role was already in the requested state
data.tupleCount	number	How many permission records were written or removed
data.tuples	array	The records that were written or removed

Errors

Status	Code	When
400	VALIDATION_ERROR	roleName is not Application:RoleName, or a feature string is the wrong shape
500	INTERNAL_ERROR	Something unexpected failed

{
  "success": false,
  "error": "roleName must be in format \"Application:RoleName\" (e.g., \"Honeycomb:Honeycomb Read\")",
  "code": "VALIDATION_ERROR",
  "details": {
    "fields": [
      {
        "field": "roleName",
        "message": "Expected format: Application:RoleName",
        "code": "INVALID_FORMAT"
      }
    ]
  },
  "correlationId": "correlation-id",
  "timestamp": "2026-10-16T00:00:00.000Z"
}