Workflows

Workflow management through the External API lets an API-token integration manage workflows through the same lifecycle that admins use in Opero. An integration can create workflows, edit drafts, publish changes, start workflows for records, move records through transitions, read history, and manage workflow tasks.

Use these endpoints when another system defines the process configuration, or when an integration needs to keep Opero workflows aligned with external approvals, document handling, billing, onboarding, or other operational work.

Before You Start

Create an API token and give it only the workflow permissions it needs. Send the token with every request:

Authorization: Bearer ek_...

External API workflow endpoints use version v1. Workflow definitions are organization-level configuration and use organization tokens. Workflow instances, runtime history, and tasks are operational data and use the company workspace context intended for the integration.

A company token should only work with runtime data for its company. Cross-company workflow reporting belongs to explicit organization reporting surfaces, not ordinary runtime task or instance screens.

Use workflow definition permissions for configuration work, runtime permissions for active workflow instances, and task permissions for task queues.

Permissions

Assignment candidate lookup is available to tokens that have at least one of these permissions: api.workflows.read, api.workflows.manage, api.workflows.runtime.execute, or api.workflows.tasks.manage.

Manage Workflow Definitions

A workflow has editable metadata and an editable draft. The draft contains the workflow design, including stages and transitions.

When you save a draft with PUT /v1/workflows/{workflowId}/draft, Opero replaces the entire editable draft definition with the content you send. Send the intended full draft state, not only a partial transition or stage change. Read the current draft first if the integration only plans to change one part.

Publishing validates the draft. If the draft is incomplete or invalid, the publish request returns a conflict error. Fix the draft and publish again.

Published versions are kept as workflow publications. You can list them and create a new draft from a previous publication when you need to restore an earlier version.

Definition Flow

For most workflow definition integrations:

1. List workflow templates or existing workflows.
2. Create a workflow directly, or create one from a template.
3. Read the editable draft.
4. Save the full draft, including stages and transitions.
5. Publish the draft.
6. Read the workflow or publication list to confirm the active version.

Work With Runtime Instances

Runtime endpoints work with workflow instances. A workflow instance tracks the active workflow lifecycle for a target record.

Before starting a workflow, check the target workflow state or create options. A target can have only one active workflow instance at a time. If an active instance already exists for the target, starting another instance fails.

After an instance starts, the integration can read the instance, its replay data, and its history. It can execute a transition when the current stage allows the selected transition and all transition conditions pass. Transition conditions still run for external API calls.

If a transition is restricted to specific dashboard roles or to the current assignee, an API token cannot satisfy those user checks on its own. Give the token api.workflows.runtime.override only when the integration is trusted to perform those restricted transitions.

Stage read-only and edit restrictions for record mutation are handled separately. Record write endpoints still use api.workflows.bypassMutationGuard when a token needs to edit a record that is protected by its current workflow stage.

Runtime Flow

For most runtime integrations:

1. Read create options or the target workflow state.
2. Start a workflow instance for the target record.
3. Read the instance, replay, or history for synchronization.
4. Execute an allowed transition when the external process reaches the next step.
5. Re-read the instance or history to confirm the new stage.

For a custom object record, include the module and object keys whenever targetType is DYNAMIC_OBJECT_RECORD:

GET /v1/workflows/runtime/targets/DYNAMIC_OBJECT_RECORD/rec_123?moduleKey=sales&objectKey=deal
Authorization: Bearer ek_...

Tasks And Assignment

Workflow task endpoints help integrations build task queues or synchronize assignments.

Use api.workflows.tasks.read to list and read tasks. Use api.workflows.tasks.manage to reassign an open task. Reassignment updates the task and the related workflow instance assignment, and the change appears in workflow history.

Use assignment candidate lookup before assigning or reassigning work. It returns the members or roles that are valid for the workflow assignment context.

Audit, History, And Automation

External workflow actions are recorded as API-token actions. History and audit entries show that the API token performed the action rather than a dashboard user.

Workflow automation can react to transitions and completions caused by external API calls. The event source identifies the API token, so rules and logs can distinguish API-driven changes from dashboard-driven changes.

Workflow state reads are actor-sensitive. External workflow GET endpoints intentionally do not use shared HTTP caching.

Troubleshooting

Related Pages

• API Tokens
• Token Security
• Authentication
• OpenAPI