Create Role
- Print
- DarkLight
- PDF
Create Role
- Print
- DarkLight
- PDF
Article summary
Did you find this summary helpful?
Thank you for your feedback
Post
/api/v1/roles.create
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) orSubscriptions(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.
Default"False"
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
}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
Was this article helpful?