Create Role

Prev Next
Post
/api/v1/roles.create
Premium tag

Create a new role in the workspace. See Custom Roles for further information.

  • You can't create new roles with the same name as existing roles. For example, it is not possible to create a new role with the name admin.
  • The scope can either be Users(user level) or Subscriptions(room level).
  • Permission required: access-permissions

Changelog

Version Description
6.0.0 Moved to Enterprise plan.
3.15.0 The endpoint is no longer used to update roles.
0.70.0 Added
Header parameters
X-User-Id
stringRequired

The authenticated user ID.

ExamplerbAXPnMktTFbNpwtJ
X-Auth-Token
stringRequired

The authenticated user token.

ExampleRScctEHSmLGZGywfIhWyRpyofhKOiMoUIpimhvheU3f
Body parameters
Example 1
{
  "name": "Test Role",
  "scope": "Users",
  "description": "Testing Role for API",
  "mandatory2fa": false
}
object
name
string Required

Enter the new role's name.

ExamplenewRole
scope
string

The new role's scope. The scope can either be Users (user level) or Subscriptions (room level). The default value is Users.

ExampleSubscriptions
description
string

Enter a description for the new role.

ExampleRole description
mandatory2fa
boolean

Whether the role should have a mandatory 2FA. The default value is false. If set to true, users assigned to this role are prompted to enter a 2FA code for certain activities.

Defaultfalse
Responses
200

OK

Success Example
{
  "role": {
    "_id": "646c431fa8c3a3ba32d0e1c4",
    "name": "support1",
    "scope": "Subscriptions",
    "description": "Role support tier 1",
    "protected": false,
    "mandatory2fa": false,
    "_updatedAt": "2023-05-23T04:37:51.161Z"
  },
  "success": true
}
Expand All
object
role
object
_id
string
name
string
scope
string
description
string
protected
boolean
mandatory2fa
boolean
_updatedAt
string
success
boolean
400

Bad Request

Example 1
{
  "success": false,
  "error": "The role properties are invalid. [error-invalid-role-properties]",
  "errorType": "error-invalid-role-properties"
}
Example 2
{
  "success": false,
  "error": "Role name already exists [error-duplicate-role-names-not-allowed]",
  "errorType": "error-duplicate-role-names-not-allowed"
}
Example 3
{
  "success": false,
  "error": "Accessing permissions is not allowed [error-action-not-allowed]",
  "errorType": "error-action-not-allowed"
}
object
success
boolean
error
string
errorType
string
401

Unauthorized

Authorization Error
{
  "status": "error",
  "message": "You must be logged in to do this."
}
object
status
string
message
string
Tags