Custom roles

Custom Roles let admins control exactly which connectors, tools, scopes, and AI models each group of users can access. They also gate sensitive features and set per-user usage caps.

Managing Custom Roles requires the Admin or Security organization role.

Key concepts

Additive membership — a user can hold multiple custom roles. Their effective access is the union across all roles.
Default role — every new member is auto-assigned to the default role. It cannot be deleted.
Restrictions compose least-restrictively — a user is only blocked from something if every role they hold blocks it.

Custom Roles restrict what a user can do. Organization Roles grant authority (Admin, Manager, etc.). Both must allow an action for it to succeed.

Managing roles

Navigate to gumloop.com/settings/organization/groups.

Creating a role

A new role starts from one of three starting points, so you rarely have to configure it from scratch:

Starter	Where it begins
No access	Everything restricted. Grant connectors, models, and features one by one.
Full access	Nothing restricted. Take away only what this group should not have.
Copy of an existing role	A duplicate of another role — its app, model, feature, and usage-limit configuration — that you then adjust.

Pick Full access when a group needs almost everything and only a few capabilities removed; picking No access for that job means re-granting every connector by hand.

Role tabs

Each role has the following tabs:

Tab	Purpose
Connectors	Per-connector control over tools and scopes
Models	Which AI models users in this role can select
Features	Toggles for sensitive capabilities
Usage Limits	Per-user concurrency and credit caps
Users	Assign members to this role
Settings	Rename, restrict newly added integrations, set as default, or delete

Connectors tab

The Connectors tab is where you control which connectors your users can access and what they can do with each one. It consolidates tools and scopes into a single per-connector view.

Overview

The main view shows all available connectors as cards. Each card shows its authentication type and the count of granted tools and scopes at a glance.

Example: Configuring GitHub access

Let’s walk through configuring GitHub access for a custom role. Step 1: Open the app Click the GitHub card (or click Add Connector and select GitHub). This opens the App Picker, where you can configure Tools and Scopes.

Step 2: Configure Tools The Tools tab shows every agent tool available for this app. Toggle individual tools on or off.

Use Select all / Deselect all for bulk changes
Search for specific tools using the search bar
Tools that are not selected will be blocked for users in this role

Step 3: Configure Scopes The Scopes tab controls which OAuth scopes users in this role can grant when connecting the app.

Only selected scopes can be authorized by users in this role
Removing a scope may affect tools that depend on it

Step 4: Save Click Save to apply your changes. The app card on the overview will update to reflect the new counts.

Removing app access

To completely remove a role’s access to an app, click the three-dot menu (⋯) on the app card and select Remove access. This removes all tool and scope grants for that app from this role.

How app restrictions compose

When a user is in multiple roles, app access composes with the least-restrictive rule:

Scenario	Result
Role A grants 3 GitHub tools, Role B has no GitHub card	User gets all GitHub tools (B is silent)
Role A grants `repo` scope only, Role B has no GitHub card	User gets all scopes (B is silent)
Role A and Role B both only grant `repo` scope	User gets only `repo` scope
Role A removes app access entirely, Role B has no card	User is unrestricted (B is silent)

A role with no card for an app is “silent” on that app, meaning it does not restrict it. Only when every role a user holds explicitly restricts an app does the restriction apply.

Models tab

The Models tab controls which AI models users in this role can select — in the agent model picker. Models a role does not allow are hidden from the picker, so members can only choose from what they are permitted to use.

Models are grouped by provider (Anthropic, OpenAI, SpaceXAI, Google, and more) with a running allowed and blocked count in the header. You can:

Toggle a whole provider on or off, or expand a provider to toggle individual models
Search for a specific model or provider
See a US-provider hosted badge on providers served by US-based providers under Zero Data Retention policies

Deprecated models are collapsed behind a +N more deprecated models link so the list stays focused on current models.

A role’s model list is bounded by the organization’s model access ceiling. If a model is blocked org-wide on the AI Model Governance page, it cannot be granted to a role here, even if it appears selectable.

Clearing every model for a role is an explicit deny-all — users in that role (and no other role that allows models) will have no selectable models and fall back to the organization’s configured fallback model.

How model access composes

Like apps, model access composes least-restrictively across a user’s roles: a user can select a model if any role they hold allows it. A role that leaves its Models tab untouched is “silent” and does not restrict models. For ordinary agent runs, a disallowed model can fall back to the organization’s Fallback Model. Concrete model requests from Computer scripts are different: a disallowed model returns an error instead of silently substituting another model.

Features tab

Controls sensitive capabilities. A user gets a feature if any assigned custom role grants it. The organization Admin role does not by itself bypass the Model access on Computer restriction.

Feature	What it allows
Team creation	Create new teams within the organization
Team credential addition	Add credentials to teams the user has admin access to
Agent email inbox management	Enable, change, or disable email inboxes for agents
Agent browser	Give agents a browser and use it on agents they run
Model access on Computer	Let agents call permitted models from Computer scripts, subject to approval. See Code sandbox & secrets.
Agent incognito mode	Run agent chats without saving messages to history
Public flow and interface sharing	Share flows and interfaces publicly
External chat sharing	Share chats outside the organization or publicly
External artifact sharing	Share files outside the organization or publicly
External password-protected artifact sharing	Share files outside the organization behind a password
Flow modification	Create, update, or delete flows and workbooks
Workflow incognito mode	Run workflows without saving run data to history
Agent modification	Create, update, or delete agents
Skill creation	Create skills within the organization
Agent-owned credentials	Configure agents to use a pinned account or connection for everyone who can access the agent
Brain access	View and search Brain knowledge sources
Brain source management	Add, update, sync, share, or delete Brain sources

Features marked with a shield icon are denied by default for enterprise users unless explicitly granted. Others are allowed by default.

Model access on Computer is a separate feature grant from the Models allowlist. Both must permit the call; approving a script does not override either restriction.Skill creation covers new skills only. With it turned off, an agent that tries to save a new skill skips it and reports that skill creation has been restricted by your organization admin; editing skills that already exist is unaffected and stays governed by each skill’s own access.

Usage limits tab

Per-user caps that override organization-wide defaults.

Cap	Effect
Concurrent Run Limit	Max simultaneous workflow runs per user
Concurrent Agent Limit	Max simultaneous agent interactions per user
Monthly Credit Cap	Max credits per billing month
Credit Usage Notifications	Email alerts at thresholds (50%, 80%, 100%)
Per-Chat Credit Warnings	Pause chat for approval when a single chat’s spend crosses a threshold

Caps compose by taking the maximum across a user’s roles.

Monthly credit caps can also be read and set programmatically, so an internal credit-management system can act as the control plane. See the List, Get, and Set Custom Role Credit Limit API endpoints.

Per-chat credit warnings

Per-Chat Credit Warnings pause a user’s chat for approval whenever the credit spend in that single chat crosses a threshold. This prevents runaway conversations from silently burning through credits.

Click Configure to open the threshold picker. Toggle the default thresholds (5,000, 10,000, and 25,000 credits) or add a custom value.

Per-Chat Credit Warnings configuration modal with default thresholds at 5,000, 10,000, and 25,000 credits and an Add custom threshold button

When a chat hits an enabled threshold, the agent pauses and creates an Action Request that the user (or an admin) must approve before the conversation continues.

The default values are recommended to prevent runaway chats while ensuring normal usage is not interrupted.

Multi-role resolution: thresholds compose by taking the maximum across all of a user’s custom roles. For example, if a user belongs to Role A (warning at 5,000 credits) and Role B (warning at 10,000 credits), their chat will pause at 10,000 credits — the higher, least-restrictive value wins.

Users tab

Assign members to this role. Adding a user here does not remove them from any other role.

Settings tab

Role Name and Description — rename the role and describe what it’s for
Disable New Connectors by Default: blocks newly released connectors and newly added MCP servers until an admin enables them.
Show Only Allowed Connectors: shows members only the connectors their roles allow.
Make Default Role: makes this role the organization’s default. To replace an existing default, make another role the default.
Delete Role — irreversible; members fall back to the default role

Restricting newly added integrations

Gumloop ships new connectors and MCP servers regularly. Turn on Disable New Connectors by Default to hold newly added access back for this role until an admin enables it. The restriction also applies to newly added OAuth-only connectors. Connectors already granted to the role are not automatically revoked or retroactively blocked. Review existing grants separately if you want to remove them.

Turn it on

Enable Disable New Connectors by Default in the role’s Settings tab. Existing connector grants are left unchanged.

New integrations arrive blocked

As Gumloop releases integrations, they are added to this role’s blocked list automatically instead of becoming available.

Approve what you want

An admin unblocks a specific integration for the role from the Connectors tab, the same way any other connector access is granted.

Newly released Gumloop integrations are restricted by a release job, so restrictions may not appear immediately when an integration ships. MCP servers your organization adds are restricted when they are created.

There is also an organization-wide version of this setting. Instead of enabling the toggle role by role, it restricts newly released integrations for every custom role in the organization, including roles created after it is turned on.

Access is a union across roles: a user who is also in a role without this restriction still gets the new integration. To hold a new integration back from someone, every role they belong to has to block it.

SCIM and IdP group sync

If your organization uses SCIM provisioning, IdP groups can be mapped to custom roles automatically.

How it works

IdP groups map to custom roles via a curated mapping table (or name-based mode)
Users receive the union of every matched role — there is no priority
Only mapped roles are added or removed. Unmapped role assignments stay as they are. New users with no match still get the default role.

Notes

A user in multiple mapped IdP groups is assigned all of the matched roles
Team (project) sync is configured independently of the role direction
With Use mapping table on, SCIM keeps a user’s existing memberships when no mapped IdP group matches (clearing the table won’t strip them)

For full SCIM setup instructions, see SSO: SAML, OIDC & SCIM.

FAQ

What happens if a user is in multiple roles?

Connectors: access is the union. Blocked only if every role blocks it.
Models: access is the union. A model is selectable if any role allows it.
Features: granted if any role grants it.
Usage caps: the highest value wins (including per-chat credit warning thresholds).

What does a 'silent' role mean?

If a role has no card for an app, it has no opinion on that app. The user is unrestricted for that app by this role. Restrictions only apply when all roles agree.

Can I use the default role as a restrictive baseline?

Yes. Keep the default role restrictive, then create add-on roles that widen access for specific groups. A stricter additional role cannot narrow access already allowed by the default role or another assigned role. To remove access, change or remove the role that grants it.

Organization roles

The authority side of Gumloop’s permission model.

Connector policies

Block or tag specific tool calls and restrict OAuth domains.

Get started

Core concepts

Enterprise features

Connectors

Key concepts