Migrate Component V1 APIs
This document outlines the necessary changes to continue using the component REST APIs after upgrading to Camunda 8.8—if migration to the new Orchestration Cluster REST API is not yet possible.
In this context, components refer to the standalone Camunda applications Operate and Tasklist, each exposing its own V1 REST API.
As of version 8.8, the V1 component APIs are deprecated. We strongly recommend migrating to the Orchestration Cluster REST API where possible.
Migrate V1 APIs
With Camunda 8.8, permissions for resource access have been reworked. For the V1 APIs, this means that access to endpoints now depends on specific read and write permissions for related resources.
To continue using the V1 APIs, users and clients must be assigned the appropriate permissions under the new authorization model.
Users now require wildcard (*) permissions for the resource type and permission type being accessed.
For guidance on assigning permissions in Identity, see the Identity authorization guide.
Mapping Operate permissions to new authorizations
To maintain the same access level for the Operate V1 API, apply the following authorizations:
operate-api:read is replaced by:
PROCESS_DEFINITION:*:READ_PROCESS_DEFINITION,READ_PROCESSINSTANCEDECISION_DEFINITION:*:READ_DECISION_DEFINITIONDECISION_REQUIREMENTS_DEFINITION:*:READ
operate-api:write is replaced by:
PROCESS_DEFINITION:*:DELETE_PROCESS_INSTANCES
Operate V1 API permission matrix
To enable more fine-grained access control, the matrix below details the required permissions for each Operate V1 API endpoint.
Ensure the user has general access (resource ID *) for each listed resource and permission type.
| Endpoint | Resource Type | Permission type |
|---|---|---|
POST /v1/process-definitions/search | PROCESS_DEFINITION | READ_PROCESS_DEFINITION |
GET /v1/process-definitions/:key | PROCESS_DEFINITION | READ_PROCESS_DEFINITION |
GET v1/process-definitions/:key/xml | PROCESS_DEFINITION | READ_PROCESS_DEFINITION |
POST /v1/decision-definitions/search | DECISION_DEFINITION | READ_DECISION_DEFINITION |
GET /v1/decision-definitions/:key | DECISION_DEFINITION | READ_DECISION_DEFINITION |
POST /v1/decision-instances/search | DECISION_DEFINITION | READ_DECISION_INSTANCE |
GET /v1/decision-instances/:id | DECISION_DEFINITION | READ_DECISION_INSTANCE |
POST /v1/flownode-instances/search | PROCESS_DEFINITION | READ_PROCESS_INSTANCE |
GET /v1/flownode-instances/:key | PROCESS_DEFINITION | READ_PROCESS_INSTANCE |
POST /v1/variables/search | PROCESS_DEFINITION | READ_PROCESS_INSTANCE |
GET /v1/variables/:key | PROCESS_DEFINITION | READ_PROCESS_INSTANCE |
POST /v1/process-instances/search | PROCESS_DEFINITION | READ_PROCESS_INSTANCE |
GET /v1/process-instances/:key | PROCESS_DEFINITION | READ_PROCESS_INSTANCE |
GET /v1/process-instances/:key/statistics | PROCESS_DEFINITION | READ_PROCESS_INSTANCE |
GET /v1/process-instances/:key/sequence-flows | PROCESS_DEFINITION | READ_PROCESS_INSTANCE |
DEL /v1/process-instances/:key | PROCESS_DEFINITION | DELETE_PROCESS_INSTANCE |
POST /v1/drd/search | DECISION_REQUIREMENTS_DEFINITION | READ |
GET /v1/drd/:key | DECISION_REQUIREMENTS_DEFINITION | READ |
GET /v1/drd/:key/xml | DECISION_REQUIREMENTS_DEFINITION | READ |
POST /v1/incidents/search | PROCESS_DEFINITION | READ_PROCESS_INSTANCE |
GET /v1/incidents/:key | PROCESS_DEFINITION | READ_PROCESS_INSTANCE |
Mapping Tasklist permissions to new authorizations
To maintain the same access level for the Tasklist V1 API, apply the following authorizations:
tasklist-api:read is replaced by:
PROCESS_DEFINITION:*:READ_PROCESS_DEFINITION,READ_USER_TASK
taslist-api:write is replaced by:
PROCESS_DEFINITION:*:UPDATE_USER_TASK
Tasklist V1 API permission matrix
To enable more fine-grained access control, the matrix below details the required permissions for each Tasklist V1 API endpoint.
Ensure the user has general access (resource ID *) for each listed resource and permission type.
| Endpoint | Resource Type | Permission type |
|---|---|---|
GET /v1/forms/:formId | PROCESS_DEFINITION | READ_USER_TASK |
POST /v1/tasks/search | PROCESS_DEFINITION | READ_USER_TASK |
GET /v1/tasks/:taskId | PROCESS_DEFINITION | READ_USER_TASK |
PATCH /v1/tasks/:taskId/assign | PROCESS_DEFINITION | UPDATE_USER_TASK |
PATCH /v1/tasks/:taskId/unassign | PROCESS_DEFINITION | UPDATE_USER_TASK |
PATCH /v1/tasks/:taskId/complete | PROCESS_DEFINITION | UPDATE_USER_TASK |
POST /v1/tasks/:taskId/variables | PROCESS_DEFINTION | UPDATE_USER_TASK |
POST /v1/tasks/:taskId/variables/search | PROCESS_DEFINITION | READ_USER_TASK |
GET /v1/variables/:variableId | PROCESS_DEFINITION | READ_USER_TASK |