Custom Roles (formerly “permission groups”) provide enterprise-grade access control for organizations. Administrators can create named roles that restrict access to apps, agent tools, workflow nodes, and sensitive features, and that pin per-user usage caps. Custom Roles are additive: a user can hold any number of custom roles at the same time, and their effective access is composed across all of them.Documentation Index
Fetch the complete documentation index at: https://docs.gumloop.com/llms.txt
Use this file to discover all available pages before exploring further.
Custom Roles vs. Organization Roles. These are two complementary systems:
- Organization Roles grant authority (Admin, Manager, Security, Analytics, Templates, and so on). A user can hold multiple organization roles and their permissions are the union.
- Custom Roles (this page) restrict what a user can do — feature toggles, app scopes, agent tool allow-lists, node denylists, and per-user usage caps. A user can hold multiple custom roles, and the effective restriction is composed across all of them.
What Are Custom Roles?
Every organization member belongs to one or more custom roles. New members are automatically added to the default custom role, and admins can layer additional roles on top to grant or restrict specific capabilities.Multi-Membership
A user can hold multiple custom roles simultaneously. Their effective access is composed across every role they hold.
Automatic Default
New members automatically join the default custom role and stay in it as a fallback.
Enterprise Security
Granular controls for app scopes, agent tools, nodes, sensitive features, and per-user usage caps.
How Multiple Roles Compose
Because users can hold multiple custom roles, every restriction is composed before being enforced. The composition rule depends on the kind of restriction.Resource restrictions are a least-restrictive overlay
App scopes, agent tools, nodes/operators, and disabled MCP servers all use the same composition rule:A user is blocked from a resource only when every custom role they hold blocks that same resource. A role that has no opinion (no row) on a resource counts as access.In practice this means:
- An allow-list restriction (App Scopes, Agent Tools) in one role does not restrict the user if any other role they hold is silent on that resource.
- A deny-list restriction (Nodes, MCP servers) in one role does not block the user if any other role they hold is silent on the same item.
- A role with no rows in any tab — a “blank role” — unlocks all custom-role resource restrictions for everyone in it (subject to normal RBAC, item ACLs, tier gates, and feature defaults).
| Restriction | Polarity | Group A | Group B | Effective for a user in both |
|---|---|---|---|---|
| App scopes | Allow-list | Allows Gmail gmail.read only | No Gmail row | Gmail scopes are unrestricted (B is silent) |
| Agent tools | Allow-list | Allows Slack send_message only | No Slack row | All Slack tools are unrestricted (B is silent) |
| Nodes | Deny-list | Blocks HTTP Request | No row for HTTP Request | HTTP Request is unrestricted (B is silent) |
| MCP servers | Deny toggle | Disables Notion server | No Notion server row | Notion server is not disabled (B is silent) |
Single-role behavior is unchanged. If a user only belongs to one custom role, that role’s allow-list / deny-list / disabled-server rows apply directly.
Sensitive Feature Access is an additive grant
The Features tab lists capabilities that are gated by default for non-admin members (creating teams, adding team credentials, building MCP nodes, sharing publicly, and so on). When a user is in multiple roles, the sensitive feature is granted if at least one of their roles grants it.Usage caps take the most generous value
Per-user Concurrent Run Limit, per-user Concurrent Agent Limit, and per-user Monthly Credit Cap compose by taking the maximum value across the user’s roles. This means adding a user to a more permissive role lifts their cap rather than tightening it.Policy denies and enterprise defaults
Boolean policy denies (workflow modification restrictions, agent creation restrictions, and similar toggles) compose two ways:- Regular policy denies (
DENIED_IF_ALL_DENY): denied only when every role explicitly turns on the restriction. A single role with the toggle off (or no metadata for the key) is enough to keep the action allowed. - Enterprise-default policy denies (
DENIED_IF_NONE_ALLOW): denied for enterprise users unless at least one role explicitly grants the capability. New members in only the default role inherit the enterprise default.
Default Custom Role
Every organization has exactly one default custom role. It serves three purposes:- Auto-assignment — every new organization member is automatically added to it the first time they join.
- Fallback — if a user is removed from every other custom role, they remain in the default role so they always have a baseline of permissions.
- Org-wide baseline — restrictions configured on the default role apply to every member, because every member is in it.
- Properties
- Common patterns
- Cannot be deleted — protected so every member always has a fallback role.
- Can be renamed — name and description are editable like any other role.
- Can be promoted — any other custom role can be set as the default; the previous default loses its protected status and the new default takes over auto-assignment.
Removing the only role a user has triggers automatic re-add to the default role. Users always belong to at least the default role.
Managing Custom Roles
Accessing role management
Navigate to gumloop.com/settings/organization/groups. The list shows every custom role in your org along with its member count and whether it is the default.Creating a custom role
Click Create Role
From the main Roles & Permissions page, click Create Role and provide a descriptive name and description.
Configure restrictions
Open the new role and configure the following tabs as needed:
- App Scopes — allow-list of OAuth scopes per integration category
- Agent Tools — allow-list of tools per agent integration / MCP server
- Nodes — deny-list of workflow nodes
- Features — toggles for sensitive capabilities (team creation, credential add, MCP creation, public sharing, and similar)
- Usage Limits — per-user concurrent run, concurrent agent, and monthly credit caps
- Users — assign members
- Settings — rename, set as default, or delete
Tabs reference
App Scopes
App Scopes is an allow-list of OAuth scopes a member is allowed to grant when connecting third-party apps. The categories on the left list every integration; selecting a category lets you toggle individual scopes.
- Allow-list semantics — if a category has any selected scopes, only those scopes are allowed. If a category has no selected scopes, the role is silent on that integration and that integration is unrestricted by this role.
- Composition — for users in multiple roles, a scope is restricted only when every role they hold has explicit selections that exclude it. A silent role on the integration means the user is unrestricted for that integration.
Agent Tools
Agent Tools controls which tools agents can call when they belong to members of this role.
- Allow-list semantics — pick the specific agent tools the role is allowed to call. Tools you don’t pick are blocked for that role; tools in apps with no row are unrestricted.
- Disable Server — a per-server kill switch that prevents agents in this role from using any tool from that server.
- Composition — same least-restrictive overlay as App Scopes. A user in two roles can call any tool either role allows.
Nodes
Nodes is a deny-list of workflow nodes. Use it to remove nodes from the node library and to block existing pipelines from running them.
- Per-node toggles — turning a toggle off blocks that node for members of this role.
- Category controls — block whole categories at once.
- Disabled MCP servers — disabling an MCP server here also hides its tools from the agent tool picker.
- Composition — a node is blocked only when every custom role the user holds blocks it. Roles with no row for a node are silent.
Features
The Features tab — labeled Sensitive Feature Access — controls capabilities that are gated by default for non-admin members. A user receives the capability if any of their custom roles grants it.
- Create a team — allow members to create new teams.
- Add a credential to a team — allow members to add new credentials to a team.
- Create an MCP Node — allow members to build custom MCP nodes.
- Share publicly — allow members to set workflow / agent / interface General Access to “Anyone”.
Sensitive Feature Access is an additive grant, not a restriction. Adding a user to a role that grants a feature gives them access; removing them from that role does not affect grants from other roles they hold.
Usage Limits
Per-user caps that override the organization-wide defaults.
| Cap | Effect |
|---|---|
| User Concurrent Run Limit | Maximum simultaneous workflow runs per user. |
| User Concurrent Agent Limit | Maximum simultaneous agent interactions per user. |
| User Monthly Credit Cap | Maximum credits a user can spend per billing month. Setting this on a role rebalances credit limits for its members at write time. |
| Credit Usage Notifications | Email thresholds (e.g. 50%, 80%, 100% of cap) that trigger usage alerts. |
Usage caps compose by taking the maximum across a user’s custom roles. Adding a user to a role with a higher cap raises their cap; it does not lower it.
Users
The Users tab lets you assign members of your organization to this role. Adding a user to a role does not remove them from any other role.Settings
The Settings tab is where you rename the role, change its description, set it as the default, or delete it.
- Default Role — toggling this on promotes the current role to be the org’s default. The previous default loses its protected status.
- Delete Role — irreversible. Deleting a role removes it from every member; users remain in any other roles they hold (and at minimum, the default role).
When to give a user multiple roles
Multi-membership lets you compose access from small, single-purpose roles instead of duplicating large permission bundles. A few common patterns:Stack a baseline role with capability add-ons
Stack a baseline role with capability add-ons
Keep the default role tight (e.g. blocks all writing nodes, restricts CRM scopes). Then create small add-on roles like CRM Writer, HTTP Power User, or Public Sharing and grant them to specific people. Each add-on widens access without requiring you to copy the whole baseline.
Give cross-functional users multiple team roles
Give cross-functional users multiple team roles
A team lead who works with both Sales and Finance can be assigned both the Sales Tools and Finance Tools roles. They get the union of allowed apps, scopes, and tools without you having to maintain a third combined role.
Promote a user temporarily
Promote a user temporarily
Add a member to a higher-cap Heavy Automation role for a project (raising their concurrent run / credit caps without changing their default). Remove the role when the project ends — they fall back to their default cap automatically.
Layer sensitive feature grants
Layer sensitive feature grants
Use one role to grant Create a team, another to grant Share publicly, and assign each to the right subset of people. Sensitive Feature Access is additive, so you only grant what each user actually needs.
Real-world use cases
Sales team CRM access
Sales team CRM access
Scenario: Your sales team needs Salesforce access; other teams shouldn’t.Solution:
- Default role blocks Salesforce nodes and Salesforce OAuth scopes.
- Create a Sales Tools role that allows Salesforce read/write scopes and Salesforce nodes.
- Add sales team members to Sales Tools in addition to the default role.
IT vs general users
IT vs general users
Scenario: IT needs full team management and credential rights; general users do not.Solution:
- Default role does not grant Create a team or Add a credential to a team in the Features tab.
- Create an IT Admin Tools role that grants both. Add IT staff to it.
Compliance read-only reviewer
Compliance read-only reviewer
Scenario: Auditors need to view workflows but should not run anything that writes data.Solution:
- Create a Compliance Reviewer role that blocks every “writer”-style node and disables sensitive MCP servers.
- Set it as the only role for auditors (remove them from any other role except the default, then make sure the default does not allow writes either).
Heavy automation specialists
Heavy automation specialists
Scenario: A handful of automation engineers need higher concurrent run / credit caps; everyone else should stay at default.Solution:
- Default role sets a low User Concurrent Run Limit and a modest User Monthly Credit Cap.
- Create a Heavy Automation role with much higher caps. Add automation engineers to it.
- Caps compose by max, so they get the higher caps automatically.
Business rules and enforcement
Multi-Role Membership
Users can belong to any number of custom roles. The default role is automatic; additional roles are layered on top.Removing a user from every other role keeps them in the default role.
Runtime composition
Restrictions are composed at request time. UI interactions, workflow execution, agent tool calls, and API calls all evaluate the user’s full role set.
Admin-only management
Only members with the Admin or Security organization role can create, edit, delete, or assign custom roles.
SCIM and IdP group sync
If your organization uses SCIM, IdP groups can be mapped to custom roles. SCIM group sync currently maps each user to a single target role using priority-based matching — it does not yet assign users to multiple roles. Manual assignments through the UI / API are unaffected and still support multi-membership. See SSO, SAML, and SCIM for details.Getting Started
Open Roles & Permissions
Navigate to gumloop.com/settings/organization/groups.
Review the default role
Decide whether the default role should be permissive or restrictive. Adjust App Scopes, Agent Tools, Nodes, Features, and Usage Limits accordingly.
Create add-on roles
Build small, single-purpose roles (per team, per integration, per cap tier). Keep them narrow so you can compose them.
Assign users to multiple roles
Add each member to the smallest set of roles that produces the access they need. Use the default role as their baseline.
Audit and iterate
Use audit logs to monitor role changes, and adjust caps and restrictions based on actual usage.
For additional support with Custom Roles, contact your Gumloop support team at support@gumloop.com or reach out in your dedicated Slack channel.
See Also
Organization Roles
The authority side of Gumloop’s permission model — Admin, Manager, Security, and so on.
App Policies
Block or tag specific tool calls, restrict OAuth domains, and claim provider workspaces.
Rate Limits
How per-user caps interact with org-wide concurrency limits.
Credentials Management
How to manage authentication credentials across your organization.