In the Flowable Platform user permissions are only applied on the REST API level. This means that when working with the Java API there are no restrictions when performing queries.

The permissions apply on all REST APIs whether they exist in the Flowable Platform or are part of the Flowable Open Source (OSS) REST APIs.

In the following sections will explain how the different permissions work.

Normal Users

The following rules apply to normal users. See the Tenant section for how tenant rules are applied and the Administrator section for how administrator user rules are enforced.

Querying and Accessing Instances

When a user requests is executed via a REST API then each query is augmented to only query for all instances, definitions, etc. that the particular user has access to. Having access means that the user is the owner, starter, assignee or participant of an instance, either directly as an individual or indirectly as a member of the group.

This means that when a user queries for an instance, only the instances where that user is involved in will be returned.

When checking for single instances permission the entire hierarchy of the instance is checked. If a user has access to a parent instance then the user will also have access to the child instance, and the children of the child instances, etc. all the way down to the lowest leaf.

For example, if a user has started a case, within this case another user has started a process, and this process has a task. The starter of the case has access to all tasks within the case, the process itself and all tasks within the process.

Involving Users within Tasks

When a user is involved within a task then the user will also become a participant of the parent of the task (process or case).

For example, if the task was a case task then the user will gain access to the case and its children. However, it will not gain access to the parent of the case.

Candidate Users or Groups

Candidate users or groups can be used to model which users or groups have access to a particular instance.

When candidate users are used then those specific users will have access to specific instances. They will also gain access to the parent of that object.

When candidate groups are used then all members of that group will have access to a particular process, case, task, etc. However, they will not have access the parent of that object.

Accessing Definitions

When modeling a case or a process the candidateStarterUsers and / or candidateStarterGroups can be defined in order to model which users / groups are allowed to start a process / case for that particular definition. When a user queries for definitions it will only get the definitions that the user is able to start (via the "Create New" dialog). When a case or a process definition has no users defined that can start it, then normal users will not be able to start the process / case.

Note: If a definition needs to be started as a top-level case / process then it has to have the candidateStarterUsers or candidateStarterGroups defined. Otherwise, it will not appear in the "Create new" dialog.


The Flowable platform can work in a multi-tenant or single tenant mode. See Multi-tenancy for more information on how to configure and use multi-tenancy.

Single Tenant

A single tenant mode is when the users are not part of any tenant. That is the tenantId of the users is null or the empty string. All requests from such users will use any tenant information in queries or fetching instances, definitions, etc.


Multi-tenant mode is when the user has a value in the tenantId field. All requests from such users will use the tenant identifier as part of the queries or fetching instances, definitions, etc. If a user has the default tenant then the tenant identifier will not be applied (such users are special users and can access across tenants).

This means that a user in tenant acme will only query for instances, definitions, etc. in the acme tenant, i.e. it cannot see instances, definitions in any other tenant.


An administrator user is user that is a member of a group with key flowableAdministrator or a particular set of users defined via the flowable.platform.idm.additional-admin-users property.

Super Administrator

A super administrator is a user that is part of the default tenant (when in multi-tenancy mode) or has no tenant. These users are allowed to execute actions and query across all tenants and all instances.

Tenant Administrator

A tenant administrator is a user that is part of some tenant (e.g. acme). These users are allowed to execute actions and query for instances only within their own tenant.