Custom roles: reusable tool bundles that keep up with the catalog

A custom role is a named bundle of tools you build once and hand to as many people, invites, and AI-assistant endpoints as you like. It solves the problem that makes per-person tool picking painful: the tool catalog has thousands of tools and grows on most releases, so a hand-picked list starts going stale the day you save it.

Custom roles are managed on the Roles page (/roles), under Access & Team in the sidebar. Every signed-in member can open the page and read the role list; creating, editing, and deleting need Owner, Co-owner, or Administrator.

Custom roles are not the same thing as team roles. Owner, Co-owner, Administrator, and Member decide what someone can manage in the portal — billing, invites, connectors. Those are covered in Team roles and what each role can do. A custom role decides only which tools someone's AI assistant can call. The two are independent: an Administrator and a Member can hold the same custom role, and holding a custom role never grants portal permissions.

What a role is made of

A role holds two kinds of tool selection, and its tools are both of them added together.

Forever rules

A forever rule is a standing instruction rather than a snapshot, which is why new tools that match it are included automatically — you never re-edit the role when a release adds tools. Each rule has a scope and a selector:

"All read-only HaloPSA tools" and "non-destructive across everything" are both single rules. A role can hold up to 20 rules, and the editor shows how many tools each one currently matches. Rules are deliberately catalog-wide: you can write a rule for a connector before you have configured it, and the role covers it the day the credential arrives.

Scoping a rule to Everything (all connectors) with the All tools selector gives that role every tool in the catalog, forever — including tools that do not exist yet. Anyone holding it is effectively unrestricted.

Extra tools

Below the rules, Extra tools is an ordinary hand-picked list, for the handful of tools someone needs that no rule covers. These are a fixed selection: unlike a rule, they do not grow. The extras picker offers tools from connectors you have both subscribed to and configured — if a connector is missing from it, write a rule instead (rules are catalog-wide on purpose).

The live count

The editor shows the role's effective tools — how many tools the rules and the extras come to together — recomputed as you edit, next to the size of the whole catalog. The Roles page shows the same number per role, along with how many members, endpoints, and invites hold it. Treat the invite count as an upper bound: it can include invitations that were since revoked or expired.

Assigning a role

You assign roles from the page that owns the thing you are assigning to, not from the Roles page:

Who can do it: Owner, Co-owner, or Administrator — the same permission as editing someone's tools.

Changes take effect on the target's next request. Nobody has to reconnect or sign in again, and editing a role applies to everyone holding it the moment you save.

In the Edit Roles dialog, a role granted by directory sync shows checked and locked with a "via directory sync" badge — unticking it here would not remove it, so the dialog does not let you. Change the sync mapping instead. The rest of the checkboxes are yours.

How roles combine

Roles add up. Someone holding three roles can use every tool in all three. There is no way for one role to subtract a tool another role grants — if you need someone to have less, give them fewer or narrower roles.

Their own tool selection becomes "extras". Each member and endpoint still has its own tool selection, and once a role is assigned that selection turns into a short list of extras layered on top of the roles. You can see this in the buttons: Edit Tools becomes Edit Extras on any row that holds a role. While someone holds a role, there is no way back to the old "All tools (unrestricted)" setting — selecting every tool in the picker saves an explicit list of today's catalog instead, and the dialog says so.

Two consequences worth knowing before you assign a first role, and the portal warns about the first at the time:

If a member's or endpoint's tool setting is currently All tools (unrestricted), assigning their first role replaces that with the roles' tools plus any extras. That is a narrowing, and it is intentional — otherwise the role would grant nothing they did not already have.

The second: running automations is itself a tool. An unrestricted member can run AI agents; a member narrowed to connector-scoped roles loses that until a role grants it back. If someone cannot run agents after getting their first role, add the agent tools to one of their roles' Extra tools — the picker lists them.

Owners are exempt when they sign in, not through endpoints. An owner's or co-owner's own sign-in session always has every tool, so assigning a role to them changes nothing there. An AI-assistant endpoint is different, whoever owns it: the endpoint's own roles and tool list bound what that connection can call, owner's endpoint included.

Roles select tools; they do not buy them. A role can include tools from a connector plan you are not subscribed to. Those calls are still refused at call time by your plan and subscription, exactly as they would be if you had picked the tool by hand. Adding a tool to a role never changes what you are billed for or what your plan allows.

Removing the last role

Removing someone's last role does not hand them back "All tools". If their own tool setting was unrestricted, silently restoring it would take them from a curated role straight to the entire catalog, destructive tools included — so the portal locks their tool access to none instead, and stops to tell you before it saves. The warning is titled "This leaves them with no tools", and the choices are Back and Remove roles. There is no option that restores unrestricted access; give them a role or a hand-picked tool list afterwards.

You only see this when it applies. Removing a role from someone who still holds another one — including a role granted by directory sync — or whose own setting is already a specific list, just saves.

Invites that carry a role

The invite form shows a Roles picker whenever your organization has any custom role. Pick roles while composing an invitation and the new person arrives already holding them — the roles move onto their membership the moment they accept.

Two behaviors to know:

• With roles picked, the tool picker becomes the extras lane. Leave it untouched and the invitation ships with the roles' tools and nothing else. Deliberately pick tools alongside the roles and exactly that selection becomes the invitation's extras — your choice is honored.
• Re-inviting the same address adds roles, never removes them. If a pending invitation already holds roles the form does not show, sending again keeps them. To remove a role from a pending invitation, use Edit Roles on its row — that dialog is the authoritative editor.

If something goes wrong around sending, the portal tells you exactly where it stopped, and the instruction differs — follow the one on screen:

• Roles could not be assigned before sending: the invitation is still valid; fix it with Edit Roles on the pending row.
• Roles were assigned and a follow-up check failed: do not re-assign — reload the page; the roles are already there.
• The invitation stopped being pending (accepted or revoked mid-flight) just as roles were written: manage the roles on the person's Team row instead of the invitation.

Deleting a role

Deleting a role asks you to confirm first, and the confirmation tells you how many members, endpoints, and invites are about to lose it, plus how many tools the role was granting. Two guards apply:

• If this is someone's only role and their own setting was unrestricted, deleting it locks them to no tools rather than silently restoring the whole catalog — the confirmation warns you, row by row. Give them a new role or a tool list afterwards.
• A role referenced by a directory-sync mapping cannot be deleted. The delete is disabled until you remove it from the mapping.

Everyone else falls back to their own tool selection.

When two managers work at once

Every write on this surface refuses rather than overwrites when it detects someone else's change mid-edit: a role edited by another manager while your editor was open, a delete confirmed against an impact summary that changed, a role assignment saved over someone else's save. In every case the message says nothing was saved — reopen or reload to see the current state, then apply your change again. And when a save completes but a follow-up step fails, the message says "Completed … Do not retry" — believe it: the change is in, and repeating it would only trip the same someone-else-changed-this refusal.

If roles cannot be loaded

When StackJack cannot read your organization's roles (a rare, usually brief condition), the pages fail safe rather than guess: tool-permission saves are disabled with a Retry control, the Endpoints page still lets you save catalog and response settings separately, and invitations still send — an invite only ever adds roles, so nothing can be lost. Press Retry; if it persists, contact support.

Troubleshooting

A rule says it matches nothing. A category rule shows an amber "matches nothing" badge when the category it names is no longer in that connector's catalog — usually because the category was renamed. The rule grants zero tools until you edit it and pick the category again. It never silently falls back to something broader.

Someone has fewer tools than I expected. Check, in order: which roles they hold (Edit Roles), what their extras are (Edit Extras), and whether the tools you expect belong to a connector plan you are subscribed to. If they connect through an AI assistant with its own credential, that credential's roles and the member's roles both apply, and they get only what both allow.

Someone cannot run agents since I gave them a role. The narrowing removed the agent tools. Add them to one of their roles' Extra tools.

Someone has more tools than I expected. Owners and co-owners always have every tool when they sign in themselves (their endpoints are still bounded by the endpoint's roles). Otherwise, check whether one of their roles carries an Everything / All tools rule.