Create Role

Create a new role in the system.

HTTP Method	URL	Requires Auth
POST	/api/v1/roles.create	yes

• This endpoint doesn't update existing roles. See Update Role.

• 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 or Subscriptions.

Body Parameters

Key	Example Value	Description
name*	newRole	The name of the new role.
scope	Subscriptions	The scope of the new role. The default value is Users.
description	Role description	A description for the new role.
mandatory2fa	true	Whether the role should have mandatory 2FA. The default value is false.

Example Call

curl --location 'http://localhost:3000/api/v1/roles.create' \
--header 'X-User-Id: rbAXPnMktTFbNpwtJ' \
--header 'X-Auth-Token: 3K3OqbQcU9H6FiZNEE5lxTTEfXyWxypWRJjvl_2ySOm' \
--header 'Content-Type: application/json' \
--data '{
        "name": "Test Role",
        "scope": "Users",
        "description": "Testing Role for API",
        "mandatory2fa": false
    }'

Example Response

Success

{
    "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
}

Error

Any of the following errors can occur:

• Authorization: Requires an authentication token for the request to be made.

• Invalid Role Properties: Occurs when the required payload arguments are not provided when making the request.

• Duplicate Role Names: This occurs when the role's name already exists on the workspace.

Authorization

{
    "success": false,
    "error": "unauthorized"
}

Invalid Role Properties

{
    "success": false,
    "error": "The role properties are invalid. [error-invalid-role-properties]",
    "errorType": "error-invalid-role-properties"
}

Duplicate Role Names

{
    "success": false,
    "error": "Role name already exists [error-duplicate-role-names-not-allowed]",
    "errorType": "error-duplicate-role-names-not-allowed"
}

Change Log

Version	Description
0.70.0	Added
3.15.0	Is no longer used to update roles
6.0.0	Moved to enteprise edition.