create-role.md

Create Role

Create a new role in the system.

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

{% hint style="info" %}

• This endpoint doesn't update existing roles. See update-role.md.
• 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. {% endhint %}

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.

{% tabs %} {% tab title=" Authorization" %}

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

{% endtab %}

{% tab title="Invalid Role Properties" %}

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

{% endtab %}

{% tab title="Duplicate Role Names" %}

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

{% endtab %} {% endtabs %}

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.