Roles and Permissions¶

Imbi uses role-based access control. A permission lets a principal do one action, for example project:write. A role is a set of permissions. A user or a service account gets a role from a membership in an organization. Teams do not give roles.

A platform administrator (is_admin) passes every permission check. This is not the same as the admin role. See Platform administrators.

Built-in roles¶

imbi-api setup seeds seven roles. Four roles are for people. Three roles are for the service accounts of Imbi services.

default and readonly do not include the read permissions for secrets, runner pools, service accounts, auth providers, MCP servers, and scoring policies. The permission table shows the full grants.

The built-in roles are system roles. You cannot change their permissions or delete them. After an upgrade, run imbi-api setup-permissions to add new permissions and refresh the grants of the built-in roles. See Initial Setup.

The imbi-workflows role does not include integration:act-as-service. An operator must grant it, as ADR 0017 requires for every autonomous principal.

Assign a role¶

1. Open Admin > Global Admin > User Management.
2. Click the user.
3. Click Edit User.
4. Under Memberships, select the organization and select the role.
5. Click Save Changes.

See Users, Teams, and Organizations.

Create a custom role¶

Roles are global. You can use one role in each organization.

1. Open Admin > Global Admin > Roles.
2. Click New Role.
3. Enter the name and the slug, for example "Team Lead".
4. Under Permissions, select the permissions.
5. Click Create Role.

Permissions across organizations¶

A user can be a member of many organizations, with a different role in each. Imbi uses two rules to calculate the permissions of a request:

1. Organization routes. These routes use only the role in the organization of the path. A principal that is not a member of that organization gets 403 organization_forbidden. A platform administrator must also be a member.
2. All other routes. These routes use the union of the roles in all the organizations of the principal.

An API key can have scopes. On both types of route, the scopes of the key limit the permissions that the roles give.

The organization routes are these routes under /organizations/{org_slug}/:

The project deployment and sync routes also return 404 when the project is not in the organization of the path.

These requests also use only the role in one organization:

• GET /harness/pools with the organization parameter.
• The secret binding that you make when you bind a credential to an MCP server.
• A label move on the system prompt of an agent (see Prompt labels).

All other routes use the union, for example projects, teams, blueprints, prompts, and users.

Example: a user has developer in organization A and readonly in organization B. The user can create a project in organization B, because the projects routes use the union. The user cannot create an agent in organization B, because the agents routes use only the readonly role.

The UI uses the same rules. GET /users/me returns the union in permissions and the permissions of each membership in organizations[].permissions. On the pages of the organization routes, the UI shows a button only when your role in that organization gives the permission. A platform administrator who is a member of that organization sees every button there, whatever the role. In the example, the user does not see Pause and Cancel on the tasks of organization B.

Special rules¶

Prompt labels¶

prompt:promote lets you move any prompt label. No built-in role other than admin has it.

The system prompt of an agent is the prompt agents/<org>.<agent>. To move a label of this prompt, agent:write in that organization is also sufficient. Thus a developer can save a change to an agent and make the agent use it. See Prompts and Agents.

Runner pools¶

Only platform administrators can change runner pools. This is not a permission, because an organization administrator can grant a permission to a role. harness_pool:read lets a member see the pools that serve the organization.

Workflow activation¶

To activate a workflow, you also need the permissions that its steps need. For example, a Schedule step needs scheduled_task:create, and a Webhook step needs webhook:update. See Workflows.

Permission table¶

Permissions follow a resource:action pattern. The table shows each permission that imbi-api setup seeds, and the built-in roles that have it.

See Agents, Agent tasks, Workflows, Prompts, and Secrets.