# 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 "actions" that correspond with the names of endpoint operations that a user with the role is allowed ("effect": "allow") or not allowed ("effect": "deny") to perform.
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 to True, 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 "actions" that correspond with the names of endpoint operations that a user with the role is allowed ("effect": "allow") or not allowed ("effect": "deny") to perform.
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.
created_ts timestamp Time at which the role was created. Measured in seconds (to three decimal places) that have elapsed since the Unix epoch(opens new window).
updated_ts timestamp Time at which the role was last updated. Measured in seconds (to three decimal places) that have elapsed since the Unix epoch(opens new window).

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 to True.
  • 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.

← Get user role →

Was this article helpful?