Getting Started

Follow these simple steps to explore the full power of yWorkflow

Login with Google

Start by logging into the application using your Google account. This provides secure authentication and allows you to manage your own workflow definitions and instances.

Open Application (opens in new window)

Note: The application uses Google OAuth for authentication. Simply click the "Sign in with Google" button to get started.

Create an Admin API Key

Once logged in, navigate to the API Keys section and create an "admin" API key. This key will be used to authenticate your API requests and provides full access to manage workflow definitions and instances.

💡 Tip: From the API keys creation page, there's a link to the Swagger UI. If you click it, your API key will be automatically configured in Swagger, so you can test the API directly from the interactive documentation without manually entering your key.

View Swagger API Documentation (opens in new window)

# Your API key will look like this:
X-API-KEY: wkf_123456789012

# Use it in API requests with the X-API-KEY header:
curl -H "X-API-KEY: wkf_123456789012" \
     https://app.yworkflow.com/api/definitions

Upload Workflow Definitions

Heads up: The yWorkflow library supports a richer workflow definition model and additional capabilities. If you want the full format and concepts, see How it works → Workflow Definition.

Use your API key to upload workflow definitions. For this live app, the API accepts a simplified definition format to keep the onboarding flow quick and easy.

First, save your workflow definition to a local file (for example leave-request.yml):

workflow:
  id: "leave-request"
  start: "draft"

  states:
    draft:
      transitions:
        submit: "approval_process"

    approval_process:
      fork:
        - "manager_check"
        - "hr_check"

    manager_check:
      owners: ["manager"]
      transitions:
        manager_deny: "draft"
        manager_approve: "final_gate"

    hr_check:
      owners: ["hr"]
      transitions:
        hr_deny: "draft"
        hr_approve: "final_gate"

    final_gate:
      mode: "wait_all"
      join: "approved"

    approved:
      type: "state"

Then upload the file using the Definitions API:

curl -X 'POST' \
  'https://app.yworkflow.com/api/definitions' \
  -H 'accept: */*' \
  -H 'X-API-KEY: wkf_123456789012' \
  -H 'Content-Type: application/yaml' \
  --data-binary @leave-request.yml

View this endpoint in Swagger UI (opens in new window)

Note: This example shows a leave request workflow with parallel approval paths. The owners field restricts who can perform transitions from specific states, and the fork and join enable parallel execution.

Create and Start Workflow Executions

Once you have a workflow definition, you can create execution instances. Each execution represents a running workflow that progresses through states. The API response shows the current state and available transitions you can perform.

curl -X 'POST' \
  'https://app.yworkflow.com/api/executions' \
  -H 'accept: application/json' \
  -H 'X-API-KEY: wkf_123456789012' \
  -H 'Content-Type: application/json' \
  -d '{
  "definitionId": "leave-request"
}'

View this endpoint in Swagger UI (opens in new window)

{
  "id": "74659490-b855-42dc-9b0f-54f8040d8778",
  "definitionId": "leave-request",
  "version": "v1",
  "status": "started",
  "currentStates": [
    "draft"
  ],
  "availableTransitions": [
    "submit"
  ]
}

Response Details:

id - Unique execution identifier
currentStates - Shows which states the workflow is currently in
availableTransitions - Lists the transitions you can perform from the current state(s)
status - Current execution status (started, completed, etc.)

Transition Between States

Use the available transitions to progress the workflow. When you transition, the workflow moves to the next state(s). Notice how the "submit" transition triggers a fork, creating parallel execution paths.

curl -X 'POST' \
  'https://app.yworkflow.com/api/executions/74659490-b855-42dc-9b0f-54f8040d8778/transitions' \
  -H 'accept: application/json' \
  -H 'X-API-KEY: wkf_123456789012' \
  -H 'Content-Type: application/json' \
  -d '{
  "transitionId": "submit"
}'

View this endpoint in Swagger UI (opens in new window)

{
  "id": "74659490-b855-42dc-9b0f-54f8040d8778",
  "definitionId": "leave-request",
  "version": "v1",
  "status": "started",
  "currentStates": [
    "hr_check",
    "manager_check"
  ],
  "availableTransitions": [
    "hr_approve",
    "hr_deny"
  ]
}

💡 Parallel Execution: After transitioning with "submit", the workflow forked into parallel states (hr_check and manager_check). Both paths execute simultaneously, and the workflow will wait for both to complete before joining at final_gate.

🔐 Role-Based Access Control: The response above only shows HR-specific transitions (hr_approve, hr_deny) because the API key used has the hr role. An API key with the manager role would see different transitions (manager_approve, manager_deny). This ensures users can only perform actions they're authorized for.

Role-Based Access Control

yWorkflow supports fine-grained access control through role-based permissions. Each state can have an owner, and API keys can be associated with specific roles, restricting access to only permitted operations.

State Ownership

Assign owners to specific states, ensuring only authorized users can perform transitions from those states.

API Key Roles

Associate API keys with roles (admin, user, viewer) to control what operations each key can perform.