Create a custom role

Create a custom role that bundles built-in policies to grant a team exactly the workflow access they need within a project.

Before you begin

You have the admin role, or a role with role:create and role-assignment:assign permissions.
You have created a project for the role assignment.
You have the project UUID for the project_id field in the API example.
A group exists for the assignment target.

About this task

Built-in roles cover common access patterns, but you can create custom roles that bundle built-in policies. To grant a team workflow access within a project, create a custom role from built-in policies, assign the role to a group, and verify the result.

Automation orchestrator ships built-in policies only. You cannot create custom policies. Custom roles reference built-in policy names such as workflow:read:project.

Procedure

Send a POST request to create a project-scoped role that references built-in policies by name.
Set project_id to your project UUID. Without project_id, the API creates a system-scoped role. You cannot assign a system-scoped role to a project.

In this example, the role allows reading the project, reading workflows, reading executions, and running executions. These built-in policies let users find the project and view and run its workflows without create, update, or delete access.
```
curl -X POST https://orchestrator.example.com/api/v1/roles \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "workflow-runner",
    "description": "Can view and run workflows within the assigned project",
    "policies": [
      "project:read:project",
      "workflow:read:project",
      "execution:read:project",
      "execution:run:project"
    ],
    "project_id": "project-id"
  }'
```
The API returns 201 Created with the role object. The role is now available for assignment in that project.

Tip:

You can also create the role in the UI. Navigate to Access Management > Roles, select Create role, choose Project scope, select the project, then select the built-in policies.
Assign the role to a user or group through Access Management > Assignments.

For steps, see Assign a role.

What to do next

Verify the role assignment as a member of the assigned group, not the admin account that created the role. An admin account can return Allowed from broader admin policies instead of the policies in your custom role.

Use the authorization check API to confirm that the custom role grants the expected permissions:

curl -X POST https://orchestrator.example.com/api/v1/authz/can_i \
  -H "Authorization: Bearer $MEMBER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "read",
    "resource_type": "workflow",
    "resource_project": "project-id"
  }'

Expected response:

{
  "allowed": true,
  "denied": false,
  "matched_policy": "workflow:read:project",
  "denial_reason": "",
  "denied_by": ""
}

Confirm that permissions the role does not include are denied. For the workflow-runner example, checking credential:read returns "allowed": false because the role does not include credential policies.

You can also verify in the UI. Open My Profile, select the Check my access tab, and test the target project with different resource type and action combinations.