anchor.diff:  } 
   -----
   
  -Alternatively, the endpoint ```/api/v1/users/:userUuid/permissions/:path``` provides a shortcut for querying permissions for specific users directly, e.g., for user ```anonymous```, which is essentially inheriting all permissions from role ```anonymous```.
  +Alternatively, you can use query the element using the respective API endpoint (e.g. link:++raml#project__nodes__get++[```GET /api/v1/projectName/nodes```]) and use the ```role``` query parameter to find out another role's (i.e. ```anonymous```) permissions on the element:
  +
  +.Try the example with user ```admin```
  +[TIP]
  +https://demo.getmesh.io/api/v1/demo/nodes/88fac3fbc61041c1bac3fbc610d1c182?role=10447951fd264e6a847951fd266e6ae6
  +
  +[source,bash]
  +-----
  +GET https://demo.getmesh.io/api/v1/roles/10447951fd264e6a847951fd266e6ae6/permissions/projects/217f8c981ada4642bf8c981adaa642c3/nodes/88fac3fbc61041c1bac3fbc610d1c182
  +
  +RESPONSE
  +...
  +  "permissions" : { // permissions of requesting user admin
  +    "create" : true,
  +    "read" : true,
  +    "update" : true,
  +    "delete" : true,
  +    "publish" : true,
  +    "readPublished" : true
  +  },
  +  "rolePerms" : { // permissions of requested role anonymous
  +    "create" : false,
  +    "read" : false,
  +    "update" : false,
  +    "delete" : false,
  +    "publish" : false,
  +    "readPublished" : true
  +  }
  +  ...
  +-----
  +
  +==== Querying User Permissions
  +The endpoint link:raml/#users__userUuid__permissions__path__get[```GET /api/v1/users/:userUuid/permissions/:path```] provides a shortcut for querying permissions for specific users directly, e.g., for user ```anonymous```, which is essentially inheriting all permissions from role ```anonymous```.
   
   .Try the example
   [TIP]
  
positive.code: 
  == Permissions
  
  Permissions exist between roles and other elements (including other roles). By organizing link:building-blocks.html#_user[users] with link:building-blocks.html#_group[groups] and by assigning link:building-blocks.html#_role[roles] to groups, users inherit permissions on elements.
  // TODO image (anonymous, and other roles having different permissions)
  
  Most responses within Gentics Mesh will contain a list of permissions which may indicate that CRUD operations on the returned element are restricted in a way:
  
  .Try the example
  [TIP]
  https://demo.getmesh.io/api/v1/demo/nodes/88fac3fbc61041c1bac3fbc610d1c182?version=published
  
  
  [source,json]
  -----
  ...
    "permissions" : {
      "create" : false,        //create other nodes
  
negative.code: 
  === Assigning & Revoking Permissions 
  
  The link:raml#roles__roleUuid__permissions__pathToElement__post[```POST /api/v1/roles/:roleUuid/permissions/:path```] API endpoint can be used to assign or revoke permissions to/from a role. 
  
  * It is important to note that permissions can be granted on individual elements and onto a set of elements, which is identified by the element path name (e.g.: ```/users/:uuid``` and ```/users```).
  
  * Furthermore, the endpoint offers the property ```recursive``` for applying permissions recursively on child elements.
  
  //COMMENT: This info is interesting for mesh developers, not mesh API users.
  //In order to ensure that roles are able to invoke CRUD operations on objects they have created or would have been able to create in the first place, CRUD permissions are assigned to those roles. 
  
  //This is demonstrated by the following example:  
  
  //* User John is assigned to Role A. Role A grants him to create a new child Node in a parent Node.
  //* User Mary is assigned to Role B. Role B grants her to also create a new child //Node in the same parent Node.
  //* When John creates a new Node the permission system identifies Role B as a role that would also be able to create the object. Therefore CRUD permissions are assigned in between Role A and B and the newly created object.
  
  Following, we go through all Gentics Mesh objects that can be subject to permissions.  
  
  ==== How to grant Permissions on Users
  
  In order to grant permission on individual or all users, one need to specify the path to be either ```/users/:uuid``` or ```/users```, respectively.
  
  Applying permissions on ```/users``` recursively will affect all users.
  
  //COMMENT: This info is interesting for mesh developers, not mesh API users.
  // However, applying permissions on ```/users/:uuid``` recursively will have no effect on referenced elements such as node references.
  
  TIP: If you need to grant permission on users of a specific group, please use the ```/groups/:uuid``` element path together with property ```recursively```.
  
  ===== Example
  The following example shows how to grant the ```Editor Role``` role the permission to read all users. Since this is an operation to be performed on a set of users, the element path ```/users``` needs to be used together with property ```recursive=true```.
  
  
  NOTE: Links used in the example require prior authentication with user admin (credentials: admin/admin). Please refer to the link:references.html#_authentication[authentication] section to learn about the different authentication mechanisms provided by Gentics Mesh. The https://chrome.google.com/webstore/detail/postman/fhbjgbiflinjbdggehcddcbncdddomop?hl=en[Postman] Chrome extension can be used to build and invoke requests from your browser to Gentics Mesh.
  
  [source,bash]
  -----
  POST https://demo.getmesh.io/api/v1/roles/6754d83b086244d894d83b086204d87f/permissions/users
  
  BODY
  {
    "permissions": {
      "create": false,
      "read": true,
      "update": false,
      "delete": false,
      "publish": false,
      "readPublished": false
    },
    "recursive": true
  }
  
  RESPONSE
  {
      "message": "Permission for role Editor Role updated."
  }
  -----
  
  You can query the updated permissions with user ```admin```:
  
  https://demo.getmesh.io/api/v1/roles/6754d83b086244d894d83b086204d87f/permissions/users
  
  ===== Role permissions
  All possible role permissions on users are summarized in the following table.
  
  [caption=]
  .Role permissions on individual users and set of users
  [options="header"]
  |======
  | Role permission       | Element path        | Permission  | Recursive
  | Can create new users  | ```/users```        | Create      | false 
  | Can read all users    | ```/users```        | Read        | true 
  | Can update all users  | ```/users```        | Update      | true 
  | Can delete all users  | ```/users```        | Delete      | true 
  | Can read user         | ```/users/:uuid```  | Read        | false 
  | Can update user       | ```/users/:uuid```  | Update      | false 
  | Can delete user       | ```/users/:uuid```  | Delete      | false 
  |======
  
  ==== How to grant Permissions on Groups
  
  Permissions on a single or multiple groups are applied via ```/groups/:uuid``` path and ```/groups``` path respectively.
  
  * Granting permissions on ```/groups``` recursively will affect all groups.
  * Granting permissions  on ```/groups/:uuid``` recursively will affect users of the group.
  
  ===== Example
  The following example shows how to grant the ```Editor Role``` role the permission to read a specific group (i.e. ```Client Group```) and its users (i.e. ```webclient```). This operation needs to be applied recursively (i.e., ```recursive=true```), otherwise ```read``` permissions would be granted to the group, only.
  
  
  NOTE: Links used in the example require prior authentication with user admin (credentials: admin/admin). Please refer to the link:references.html#_authentication[authentication] section to learn about the different authentication mechanisms provided by Gentics Mesh. The https://chrome.google.com/webstore/detail/postman/fhbjgbiflinjbdggehcddcbncdddomop?hl=en[Postman] Chrome extension can be used to build and invoke requests from your browser to Gentics Mesh.
  
  [source,bash]
  -----
  POST https://demo.getmesh.io/api/v1/roles/6754d83b086244d894d83b086204d87f/permissions/groups/df81c23d9ff1450081c23d9ff195005e
  
  BODY
  {
    "permissions": {
      "create": false,
      "read": true,
      "update": false,
      "delete": false,
      "publish": false,
      "readPublished": false
    },
    "recursive": true
  }
  
  RESPONSE
  {
      "message": "Permission for role Editor Role updated."
  }
  -----
  
  You can query the updated permissions with user ```admin```:
  
  * https://demo.getmesh.io/api/v1/roles/6754d83b086244d894d83b086204d87f/permissions/groups/df81c23d9ff1450081c23d9ff195005e
  * https://demo.getmesh.io/api/v1/roles/6754d83b086244d894d83b086204d87f/permissions/users
  
  * or alternatively with
  https://demo.getmesh.io/api/v1/groups/df81c23d9ff1450081c23d9ff195005e?role=6754d83b086244d894d83b086204d87f
  https://demo.getmesh.io/api/v1/groups/df81c23d9ff1450081c23d9ff195005e/users?role=6754d83b086244d894d83b086204d87f
  
  ===== Role permissions
  All possible role permissions on groups are summarized in the following table.
  
  [caption=]
  .Role permissions on a specific group and multiple groups
  [options="header"]
  |======
  | Role permission        | Element path        | Permission  | Recursive
  | Can create new groups  | ```/groups```        | Create      | false 
  | Can read all groups    | ```/groups```        | Read        | true 
  | Can update all groups  | ```/groups```        | Update      | true 
  | Can delete all groups  | ```/groups```        | Delete      | true 
  | Can read group         | ```/groups/:uuid```  | Read        | false 
  | Can update group       | ```/groups/:uuid```  | Update      | false 
  | Can delete group       | ```/groups/:uuid```  | Delete      | false 
  | Can read group and its users   | ```/groups/:uuid```| Read        | true 
  | Can update group and its users | ```/groups/:uuid```| Update      | true 
  | Can delete group and its users | ```/groups/:uuid```| Delete      | true 
  |======
  
  ==== How to Grant Permissions on Roles
  
  By granting permissions on roles, you effectively grant users the right to change permissions of other users.
  
  * Permissions on a single or multiple roles are applied via ```/roles/:uuid``` path and ```/roles``` path respectively.
  * Granting permissions on ```/roles``` recursively will affect all roles.
  
  ===== Example
  The following example shows how to grant the ```Editor Role``` role permissions to create new roles and subsequently manage them (i.e., ```read```, ```update```, ```delete```) but no access to existing roles. 
  
  NOTE: Links used in the example require prior authentication with user admin (credentials: admin/admin). Please refer to the link:references.html#_authentication[authentication] section to learn about the different authentication mechanisms provided by Gentics Mesh. The https://chrome.google.com/webstore/detail/postman/fhbjgbiflinjbdggehcddcbncdddomop?hl=en[Postman] Chrome extension can be used to build and invoke requests from your browser to Gentics Mesh.
  
  [source,bash]
  -----
  POST https://demo.getmesh.io/api/v1/roles/6754d83b086244d894d83b086204d87f/permissions/roles
  
  BODY
  {
    "permissions": {
      "create": true,
      "read": false,
      "update": false,
      "delete": false,
      "publish": false,
      "readPublished": false
    },
    "recursive": false
  }
  
  RESPONSE
  {
      "message": "Permission for role Editor Role updated."
  }
  -----
  
  You can query the updated permissions with user ```admin```:
  
  * https://demo.getmesh.io/api/v1/roles/6754d83b086244d894d83b086204d87f/permissions/roles
  
  * or alternatively with
  https://demo.getmesh.io/api/v1/roles?role=6754d83b086244d894d83b086204d87f
  
  ===== Role permissions
  All possible role permissions on roles are summarized in the following table.
  
  [caption=]
  .Role permissions on a specific role and multiple roles
  [options="header"]
  |======
  | Role permission       | Element path        | Permission  | Recursive
  | Can create new roles  | ```/roles```        | Create      | false 
  | Can read all roles    | ```/roles```        | Read        | true 
  | Can update all roles  | ```/roles```        | Update      | true 
  | Can delete all roles  | ```/roles```        | Delete      | true 
  | Can read role         | ```/roles/:uuid```  | Read        | false 
  | Can update role       | ```/roles/:uuid```  | Update      | false 
  | Can delete role       | ```/roles/:uuid```  | Delete      | false 
  |======
  
  ==== How to Grant Permissions on Schemas
  
  Permissions on a single or multiple schemas are applied via ```/schemas/:uuid``` path and ```/schemas``` path respectively.
  
  * Granting permissions on ```/schemas``` recursively will affect all schemas.
  * Read permissions on a schema are needed for creating nodes based on that schema.
  
  [caption=]
  .Role permissions on a specific schema and multiple schemas
  [options="header"]
  |======
  | Role permission                           | Element path          | Permission  | Recursive
  | Can create new schemas                    | ```/schemas```        | Create      | false 
  | Can read all schemas, and create nodes    | ```/schemas```        | Read        | true 
  | Can update all schemas                    | ```/schemas```        | Update      | true 
  | Can delete all schemas                    | ```/schemas```        | Delete      | true 
  | Can read schema, and create nodes         | ```/schemas/:uuid```  | Read        | false 
  | Can update schema                         | ```/schemas/:uuid```  | Update      | false 
  | Can delete schema                         | ```/schemas/:uuid```  | Delete      | false 
  |======
  
  ==== How to Grant Permissions on Microschemas
  
  Permissions on a single or multiple microschemas are applied via ```/microschemas/:uuid``` path and ```/microschemas``` path respectively.
  
  * Granting permissions on ```/microschemas``` recursively will affect all microschemas.
  * Read permissions on a microschema are needed for creating, reading, updating, and deleting micronodes based on that schema.
  
  [caption=]
  .Role permissions on a specific microschema and multiple microschemas
  [options="header"]
  |======
  | Role permission                                     | Element path          | Permission  | Recursive
  | Can create new microschemas                         | ```/microschemas```        | Create      | false 
  | Can read all microschemas, and create micronodes    | ```/microschemas```        | Read        | true 
  | Can update all microschemas                         | ```/microschemas```        | Update      | true 
  | Can delete all microschemas                         | ```/microschemas```        | Delete      | true 
  | Can read microschemas, and create micronodes        | ```/microschemas/:uuid```  | Read        | false 
  | Can update microschemas                             | ```/microschemas/:uuid```  | Update      | false 
  | Can delete microschemas                             | ```/microschemas/:uuid```  | Delete      | false 
  |======
  
  
  ==== How to Grant Permissions on Projects
  
  Permissions on a single or multiple projects are applied via ```/projects/:uuid``` path and ```/projects``` path respectively.
  
  * Granting permissions on ```/projects/:uuid``` will also affect sub elements, i.e., used schemas, microschemas, tagfamilies & tags, nodes & sub nodes of the project.
  * Granting permissions on ```/projects``` recursively will affect all projects and their sub elements.
  
  [caption=]
  .Role permissions on a specific project and multiple projects
  [options="header"]
  |======
  | Role permission                                      | Element path           | Permission     | Recursive
  | Can create new project                               | ```/projects```        | Create         | false 
  | Can read all projects and sub elements               | ```/projects```        | Read           | true 
  | Can update all projects and sub elements             | ```/projects```        | Update         | true 
  | Can delete all projects and sub elements             | ```/projects```        | Delete         | true 
  | Can read published nodes and subnodes of all project | ```/projects```        | Read Published | true 
  | Can un/publish nodes and subnodes of all project     | ```/projects```        | Publish        | true 
  | Can read project and sub elements                    | ```/projects/:uuid```  | Read           | true 
  | Can update project and sub elements                  | ```/projects/:uuid```  | Update         | true 
  | Can delete project and sub elements                  | ```/projects/:uuid```  | Delete         | true 
  | Can read published nodes and subnodes of project     | ```/projects/:uuid```  | Read Published | true 
  | Can un/publish nodes and subnodes of project         | ```/projects/:uuid```  | Publish        | true 
  |======
  
  ==== How to Grant Permissions on Tag Families
  
  In order to grant permission on tag families the ```/:projectName/tagFamilies``` path can be used.
  
  * Granting permissions on ```/:projectName/tagFamilies/:uuid```  together with property ```recursive=true``` allows setting permissions for tags of a tag family.
  * Granting permissions on ```/:projectName/tagFamilies```  together with property ```recursive=true``` allows setting permissions for all tag families and their tags.
  
  [caption=]
  .Role permissions on tag families
  [options="header"]
  |======
  | Role permission                                      | Element path                           | Permission     | Recursive
  | Can create new tag families                          | ```/:projectName/tagFamilies```        | Create         | false 
  | Can create new tag families and tags for tagFamilies | ```/:projectName/tagFamilies```        | Create         | true 
  | Can read all tag families and tags                   | ```/:projectName/tagFamilies```        | Read           | true 
  | Can update all tag families and tags                 | ```/:projectName/tagFamilies```        | Update         | true 
  | Can delete all tag families and tags                 | ```/:projectName/tagFamilies```        | Delete         | true 
  | Can create tags in tag family                        | ```/:projectName/tagFamilies/:uuid```  | Create         | false 
  | Can read tag family                                  | ```/:projectName/tagFamilies/:uuid```  | Read           | false 
  | Can update tag family                                | ```/:projectName/tagFamilies/:uuid```  | Update         | false 
  | Can delete tag family                                | ```/:projectName/tagFamilies/:uuid```  | Delete         | false 
  | Can read tag family and tags                         | ```/:projectName/tagFamilies/:uuid```  | Read           | true 
  | Can update tag family and tags                       | ```/:projectName/tagFamilies/:uuid```  | Update         | true 
  | Can delete tag family and tags                       | ```/:projectName/tagFamilies/:uuid```  | Delete         | true 
  |======
  
  ==== How to Grant Permissions on Tags
  
  In order to grant permission on tags the ```/:projectName/tagFamilies/:uuid/tags``` and ```/:projectName/tagFamilies/:uuid/tags/:uuid``` paths can be used.
  
  * Granting permissions on ```/:projectName/tagFamilies/:uuid/tags``` together with property ```recursive=true``` allows setting permissions for tags of a tag family, otherwise the property has no effect.
  
  [caption=]
  .Role permissions on tag families
  [options="header"]
  |======
  | Role permission                | Element path                                     | Permission     | Recursive
  | Can create tags in tag family  | ```/:projectName/tagFamilies/:uuid/tags```       | Create         | false 
  | Can read tags in tag family    | ```/:projectName/tagFamilies/:uuid/tags```       | Read           | true 
  | Can update tags in tag family  | ```/:projectName/tagFamilies/:uuid/tags```       | Update         | true 
  | Can delete tags in tag family  | ```/:projectName/tagFamilies/:uuid/tags```       | Delete         | true 
  | Can read tag                   | ```/:projectName/tagFamilies/:uuid/tags/:uuid``` | Read           | false 
  | Can update tag                 | ```/:projectName/tagFamilies/:uuid/tags/:uuid``` | Update         | false 
  | Can delete tag                 | ```/:projectName/tagFamilies/:uuid/tags/:uuid``` | Delete         | false 
  |======
  
  ==== How to Grant Permissions on Nodes
  
  Permissions on a single or multiple nodes are applied via ```/:projectName/nodes``` and ```/:projectName/nodes/:uuid``` path:
  
  * ```/:projectName/nodes/:uuid``` is used to grant permissions on single nodes. 
  * ```/:projectName/nodes``` together with property ```recursive=true``` can be used to quickly grant permissions on all node of the project.
  * In order to grant permissions on sub trees of the content tree ```/:projectName/nodes/:uuid``` together with property ```recursive=true``` is to be used.
  
  [caption=]
  .Role permissions on nodes
  [options="header"]
  |======
  | Role permission                                           | Element path                    | Permission    | Recursive
  | Can create new sub nodes in all nodes of the project      | ```/:projectName/nodes```       | Create        | true 
  | Can read all project nodes (and all node versions)        | ```/:projectName/nodes```       | Read          | true 
  | Can update all nodes of the project                       | ```/:projectName/nodes```       | Update        | true 
  | Can delete all nodes of the project                       | ```/:projectName/nodes```       | Delete        | true 
  | Can read the published version of all project nodes       | ```/:projectName/nodes```       | ReadPublished | true 
  | Can publish/unpublish all nodes of the project            | ```/:projectName/nodes```       | Publish       | true 
  | Can create new sub nodes in specified node                | ```/:projectName/nodes/:uuid``` | Create        | false 
  | Can read specified node                                   | ```/:projectName/nodes/:uuid``` | Read          | false 
  | Can update specified node                                 | ```/:projectName/nodes/:uuid``` | Update        | false 
  | Can delete specified node                                 | ```/:projectName/nodes/:uuid``` | Delete        | false 
  | Can read the published version specified node             | ```/:projectName/nodes/:uuid``` | ReadPublished | false 
  | Can publish/unpublish specified node                      | ```/:projectName/nodes/:uuid``` | Publish       | false 
  | Can create new sub nodes in specified node & sub nodes    | ```/:projectName/nodes/:uuid``` | Create        | true 
  | Can read specified node & sub nodes                       | ```/:projectName/nodes/:uuid``` | Read          | true 
  | Can update specified node & sub nodes                     | ```/:projectName/nodes/:uuid``` | Update        | true 
  | Can delete specified node & sub nodes                     | ```/:projectName/nodes/:uuid``` | Delete        | true 
  | Can read the published version specified node & sub nodes | ```/:projectName/nodes/:uuid``` | readPublished | true 
  | Can publish/unpublish specified node & sub nodes          | ```/:projectName/nodes/:uuid``` | Publish       | true 
  
  |======
  
  
  ==== How to Grant Permissions on Releases
  
  Permissions on a single or multiple releases are applied via ```/releases/:uuid``` path and ```/releases``` path respectively.
  
  NOTE: Releases can not be deleted. Hence, permissions for deleting do not apply.
  
  [caption=]
  .Role permissions on a specific release and multiple releases
  [options="header"]
  |======
  | Role permission                     | Element path                        | Permission     | Recursive
  | Can create new release              | ```/:projectName/releases```        | Create         | false 
  | Can read all releases               | ```/:projectName/releases```        | Read           | true 
  | Can update all releases             | ```/:projectName/releases```        | Update         | true 
  | Can read the release                | ```/:projectName/releases/:uuid```  | Read           | false 
  | Can update the release              | ```/:projectName/releases/:uuid```  | Update         | false 
  |======
  
  
  