Manage a workflow

Creating a workflow is one part of the job. Deciding who can change it later, and who can run it, is the other. This page walks through both, plus deleting a workflow.

For the concepts behind each step, see workflow catalog and ownership for building permissions, and workflow execute permissions for who can run a workflow.

Create a workflow

Port AI/MCP

Ask Port AI in the platform, or your coding agent over the Port MCP server. Both work the same way: describe what you want built. For example:

"Build a workflow that runs a security scan on a service when I trigger it from its self-service page."

Either one creates the workflow, wires the trigger and any downstream nodes, and shows you the result before you publish it.

UI

1. Go to the workflow builder and click New workflow.
2. Add a trigger node (a self-service trigger for manual runs, or an event or schedule trigger for automatic ones), then add whatever nodes come after it.
3. Click Save when you're ready.

API

Call POST on /v1/workflows with the workflow's title and nodes:

{
  "identifier": "security_scan",
  "title": "Security scan",
  "nodes": [
    {
      "identifier": "trigger",
      "title": "Start",
      "config": {
        "type": "SELF_SERVE_TRIGGER",
        "userInputs": { "properties": {} }
      }
    }
  ],
  "connections": []
}

Set who can build it

Every workflow is an entity on the _workflow system blueprint, so the same team ownership and dynamic policies that govern any other blueprint decide who can read, edit, or delete it. See workflow catalog and ownership for the full model. This example lets the owning team edit its own workflows, and lets everyone else read them:

Port AI/MCP

Ask Port AI in the platform, or your coding agent over the Port MCP server. Both work the same way: describe the rule you want. For example:

"Let only the owning team update workflow entities. Everyone can read them."

Either one configures the permission for you.

UI

1. Go to your Data model page and find the _workflow blueprint.
2. Click Permissions.
3. Go to the Advanced (owners) section and toggle Update on.

Or, click Edit JSON and paste this directly:

{
  "entities": {
    "update": {
      "ownedByTeam": true
    }
  }
}

API

Call PATCH on /v1/blueprints/_workflow/permissions with:

{
  "entities": {
    "update": {
      "ownedByTeam": true
    }
  }
}

ownedByTeam only works once a workflow has an owning team. Assign one from the workflow catalog page, open the workflow entity and set its Owning Teams field, or update it directly with PATCH on /v1/blueprints/_workflow/entities/security_scan:

{
  "team": ["platform-team"]
}

Set who can run it

This is a separate layer, set on the trigger node itself, and controls what shows up on a user's self-service page. Unlike blueprint permissions, there's no visual policy builder here, you edit the trigger's permissions block directly, whether from the UI or the API. See workflow execute permissions for the full syntax reference. This example lets only the owning team run the workflow:

Port AI/MCP

Ask Port AI in the platform, or your coding agent over the Port MCP server. Both work the same way: describe who should be able to run it. For example:

"Let only the platform-team run the security_scan workflow."

Either one configures the trigger's permissions for you.

UI

1. Open the workflow in the workflow builder and click its trigger node.
2. In the trigger's config panel, find the permissions block and edit it directly: roles, users, or teams for a static grant, or a policy for a dynamic rule.
3. Click Save.

{
  "permissions": {
    "teams": ["platform-team"]
  }
}

API

Permissions live in the trigger node's config. Call PUT on /v1/workflows/security_scan with the full workflow definition, including the updated trigger:

{
  "identifier": "security_scan",
  "title": "Security scan",
  "nodes": [
    {
      "identifier": "trigger",
      "title": "Start",
      "config": {
        "type": "SELF_SERVE_TRIGGER",
        "permissions": {
          "teams": ["platform-team"]
        },
        "userInputs": { "properties": {} }
      }
    }
  ],
  "connections": []
}

A team can run a workflow without any ability to edit it, and vice versa. Combine the two however your org needs.

Delete a workflow

Deleting a workflow removes it and its runs permanently. It requires unregister permission on the _workflow blueprint, the same team ownership or policy model as any other delete.

UI

Open the workflow in the workflow builder, open its settings, and select Delete.

API

Call DELETE on /v1/workflows/security_scan.

Where to go next

• Workflow catalog and ownership - the full reference for building permissions.
• Workflow execute permissions - the full reference for who can run a workflow.
• Scope building permissions across teams and users - how the same team-based and dynamic policy model applies across workflows, scorecards, and the rest of your catalog.
• Manage users & teams - set up the teams used in these examples.