# Create user role
This endpoint creates a new role. A single role can be applied to multiple users.
NOTE
A user can only create a role that either matches their permissions or where permissions of the role that they are trying to create are lower than the permissions of the user who creates the role. A user cannot grant permissions they don't have themselves.
Method | Path | Operation* |
---|---|---|
POST | /roles | create_user_role |
*
In order for a user to perform the "create_user_role" operation, the "create_user_role" permission must be included in the list of allowed actions in the statement of the user's role.
# Request
Parameter | Type | In | Description | ||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
name optional | string, DEFAULT="User Role Name" | body | Name of the role. It must match the regular expression(opens new window) ^[0-9A-Za-z][0-9A-Za-z_ \-]{0,30}[0-9A-Za-z]$ . It does not need to be unique in the context of an account. | ||||||||||||
rules optional* | dictionary, DEFAULT=null | body | Access rule for a "twin" , an "entry" and/or an "identity" . If the rule evaluates to True , it allows to access the given resource. | ||||||||||||
statement optional ** | dictionary, DEFAULT={"effect": "deny", "actions": null} | body | Lists |
Attribute | Type | In | Description |
---|---|---|---|
effect required | string, value is "allow" or "deny" | body | Permission to perform an "action" applied at the level of the account. |
actions required | list | body | List of "actions" that we grant the user with the role the permission to perform. For a list of available actions, please consult the Available actions section. |
*
The "rules"
parameter is optional and does not need to be included in the request body when creating a role. If a rule for a Twin, an Entry or an Identity is not included in the request, its default value (null
) is used.
**
The "statement"
attribute is optional. If not provided, a role is created that allows the user to perform all available "actions"
("effect": "deny", "actions": null
).
In our example, we create a role with the name "Read only"
:
- We create one rule to access the
"twin"
resource ("TWIN.company == USER.company"). If the rule evaluates toTrue
, the user with the role will be able to access the Twin. - We allow (
"effect": "allow"
) the following"actions"
:"get_twin_ledger_entry"
,"get_twin_identities"
,"get_user_role"
,"get_twin_identity"
,"get_user"
, and"get_twin"
. These actions are held in the"statement"
attribute of the role.
# Response
Attribute | Type | Description | |||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
uuid | string | Role UUID. | |||||||||
name | string | Name of the role. It must match the regular expression(opens new window) ^[0-9A-Za-z][0-9A-Za-z_ \-]{0,30}[0-9A-Za-z]$ . It does not need to be unique in the context of the account. | |||||||||
account | string | Account UUID. | |||||||||
rules | dictionary | Access rules that control access to a "twin" , an "entry" and/or an "identity" . If a rule evaluates to True , it allows to access the given resource. | |||||||||
statement | dictionary | Lists |
Attribute | Type | Description |
---|---|---|
effect | string, value is "allow" or "deny" | Permission or to perform an "action" applied at the level of the account. |
actions | list | List of actions that we grant the user with the role the permission to perform. For a list of available actions, please consult the Available actions section. |
The response returns the role "Read only"
with the role UUID "3d4c3ec0-6c5f-4d32-ab23-4df8c69f142c"
:
- The role has a rule that allows the user with the role to access the
"twin"
resource if the rule"TWIN.company == USER.company"
evaluates toTrue
. - The role does not have an
"entry"
rule. - The role does not have an
"identity"
rule. - The rule allows (
"effect": "allow"
) the user to perform the following"actions"
:"get_twin_ledger_entry"
,"get_twin_identities"
,"get_user_role"
,"get_twin_identity"
,"get_user"
, and"get_twin"
"actions"
. These actions are held in the"statement"
attribute of the role.
# Status codes
Requests to this endpoint result in generic status codes. For a comprehensive list of status codes, please consult the Status codes section.
Was this article helpful?