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

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