Custom Role Recipes
Here are some ready-to-use custom role patterns for common authorization scenarios. Each recipe includes a YAML role definition and guidance on how to use it.
For background on creating custom roles, see Managing roles. For how policy statements and effects work, see Policies and permission resolution.
Restricting billing access
You may want technical staff to have full access to Monte Carlo's data features without being able to view or modify billing information. This is common when billing is managed by a finance team or department head.
Follow the extend/modify approach, combining with mcd/owner and a custom role that:
- denies billing permissions
- denies managing owners (to prevent escalation of privilege)
iam-role:
version: 2026-01-27
name: owner-no-billing
label: "Owner (No Billing)"
description: "When combined with mcd/owner, allows full access except viewing or modifying billing."
permissions:
settings/billing/*: deny
settings/authorization-groups/manage-owners: denyHow to use: Create an authorization group with both the mcd/owner role and this owner-no-billing role. Users in that group get full owner access except they cannot view or change billing information, or promote users to owner.
Managing access to sampling data
Sampling data can be sensitive, so you may want to restrict access to it.
Note that you can also disable sampling per integration or configure it more granularly by selecting which types of assets have sampling enabled at the integration level. To learn more, see here.
The permission controlling sampling data access is monitors/data-sampling/access. A second permission, monitors/data-sampling/download, controls downloading sampled data. In custom role YAML, monitors/data-sampling/read is shorthand for both. Every built-in role except mcd/asset-viewer and mcd/asset-editor grants it: mcd/owner, mcd/editor, mcd/monitor-editor and mcd/domains-manager through their monitors/*: allow wildcard, and mcd/viewer and mcd/responder through monitors/read: allow.
Granting sampling access
To grant sampling access to users who don't have it through their built-in role, follow the extend/modify approach, combining a built-in role (like mcd/editor) with a custom role that:
- allows data sampling access
iam-role:
version: 2026-01-27
name: allow-data-sampling
label: "Allow Sampling Access"
description: "Grants access to sampling data."
permissions:
monitors/data-sampling/read: allowNote: Denies beat allows when policies are resolved at the same level of specificity. So if the role you are combining this with specifies the same path (e.g., monitors/data-sampling/read: deny), deny would still win. In that case, you may need to specify the individual permissions to override.
Blocking sampling access
Conversely, set the effect to deny to explicitly block sampling data access — useful if you want to override the default grant from a built-in role such as mcd/owner or mcd/editor:
iam-role:
version: 2026-01-27
name: deny-data-sampling
label: "Deny Sampling Access"
description: "Denies access to sampling data."
permissions:
monitors/data-sampling/read: denyLimiting to subsets of sampling data
To grant access to only a subset of sampling data you must use domain authorization, which combines with roles in authorization groups to further scope the defined auth to particular assets in Monte Carlo. This restricts access to sampled data based on the assets monitored for a given monitor. The steps are:
- Create a domain that defines the subset of data you want to allow.
- In the authorization group editor, under Access, choose Restrict to domains and select your domain.
- Under Roles, include both your desired built-in role and the
allow-data-samplingrole above. Alternatively, if the built-in role already allows data sampling access, you only need to include that with the domain restriction(s).
Users in this group will only be able to access sampling data within the scope of the assigned domain(s).
Domain restrictions only narrow what a group allows. A deny isn't limited by domain: if any of a user's groups denies sampling, the deny applies in every domain, including domains where another group allows it, unless that group allows it with a more specific permission path. So you can't allow sampling in one domain and deny it in another for the same user.
Note: To restrict sampling data for all users in your account, use the sampling data restrictions in the integration settings for a given warehouse. Domain restrictions on authorization groups operate in addition to those integration-level restrictions.
Monitors-as-Code API key without sampling access
To let a CI pipeline run montecarlo monitors apply with an account-level API key that can't read sampled data, create an authorization group with both the mcd/monitor-editor role and the deny-data-sampling role above, then assign that group to the key.
To limit the key to certain domains, choose Restrict to domains under Access in the same group. The key only needs access to the domains its monitors use, so every monitor must set domains, or montecarlo.yml must set default_domain.
Managing access to Agent Observability content
Agent Observability content is the raw material of an agent's work: prompt and completion text, tool inputs and outputs, conversation transcripts, span attributes, and the rationale an LLM judge produced when scoring a conversation.
Access is controlled by agent-observability/content, which is independent of table data sampling. Previously the only way to hide agent conversations from a user was to remove their sampled-data access product-wide, which also took away table samples they may have needed for unrelated work.
A sibling permission, agent-observability/access, controls whether a user can open Agent Observability at all. It does not grant content. A user with access but not content can monitor their agents' health without reading what was said.
Every built-in role grants agent-observability/access. Content is granted by agent-observability/* on mcd/owner, mcd/editor, mcd/monitor-editor and mcd/domains-manager, and by agent-observability/read on mcd/viewer and mcd/responder. mcd/asset-viewer and mcd/asset-editor grant access only, so users on those roles cannot read Agent Observability content.
Blocking Agent Observability content
Follow the extend/modify approach and combine this custom role with a built-in role in an authorization group:
iam-role:
version: 2026-09-02
name: no-agent-observability-content
label: No Agent Observability Content
description: When combined with a built-in role, allows all standard access except reading raw Agent Observability content.
restrictions_summary: Denies conversation bodies, span content, judge rationale, alert samples and exports for AI agents.
recommended_for: Users who need to monitor agent health but should not read what the agents and their users said.
permissions:
agent-observability/content: denyHow to use: Create an authorization group with both a built-in role and this no-agent-observability-content role. Users in that group keep every other permission from the built-in role and lose only raw agent content.
Deny the exact agent-observability/content path rather than the agent-observability/* wildcard. The built-in roles grant content through agent-observability/* or agent-observability/read, and an exact statement is more specific than either, so the exact deny wins. A wildcard-against-wildcard deny would tie instead of overriding.
Granting Agent Observability content
To grant content to users who do not have it through their built-in role — Asset Viewers and Asset Editors — combine their built-in role with:
iam-role:
version: 2026-09-02
name: allow-agent-observability-content
label: Allow Agent Observability Content
description: Grants access to raw Agent Observability content.
permissions:
agent-observability/content: allowWhat a restricted user still sees
Restricting content does not remove Agent Observability. A restricted user keeps the agent list, Summary metrics, trace and conversation lists with their metadata, span structure and timing, tool-call charts, monitors and alerts.
What they lose is the content itself: conversation bodies, span content and attributes, evaluation rationale, evaluated-sample drill-downs, alert samples, the Explain and Evaluate actions, exports, and Troubleshooting on Agent Observability alerts.
Restricted surfaces show an explicit restricted state rather than failing or appearing empty, so a user can tell the difference between "there is nothing here" and "you may not see this".
Do not confuse
agent-observability/*withai-agents/*. The two are unrelated:ai-agents/*governs Bayes, Monte Carlo's own AI teammate, and its troubleshooting and triage skills, whileagent-observability/*governs Agent Observability — the monitoring of your AI agents. Denying the wrong one will not have the effect you intend.
Controlling access to specific types of monitors
Monitor management permissions are organized by monitor type (e.g., monitors/management/custom-sql/*, monitors/management/table/*). This lets you define custom policies that control which types of monitors specific users can access, draft, or edit. See IAM Resources and Permissions for the full list of monitor type permission paths.
Combine these custom roles with a built-in role like mcd/monitor-editor in an authorization group using the extend/modify approach. The user retains all other permissions from the built-in role while the custom role overrides only the monitor type access you specify.
Monitor type access also controls alerts. Users only see alerts from monitor types they can access, so denying a type also hides its alerts.
When Monte Carlo adds a monitor type, a custom role that lists types one by one doesn't include it. For example, users with such a role don't see job monitor alerts until monitors/management/job/access is added to the role. Roles that use a wildcard such as monitors/*, monitors/management/* or monitors/management/read include new types automatically.
Blocking a specific monitor type
To exclude a specific monitor type, deny its permissions. For example, custom SQL monitors allow users to execute arbitrary SQL queries against your data warehouse — some organizations want to restrict this to a smaller set of trusted users to prevent accidental costly queries:
iam-role:
name: no-custom-sql-monitors
label: No Custom SQL Monitors
description: Allows using/managing all kinds of monitors except custom SQL.
restrictions_summary: Denies accessing, drafting, or editing custom SQL monitors.
recommended_for: Users in our organization who should not be able to design
custom SQL monitors.
permissions:
monitors/management/custom-sql/*: denyHow to use: Create an authorization group with both the mcd/monitor-editor role and this no-custom-sql-monitors role. Users in that group get full monitor editing capabilities except they cannot view, create, or modify custom SQL monitors.
The monitors/management/custom-sql/*: deny wildcard denies all operations on custom SQL monitors — access, edit, and draft. Because this is more specific than the broader monitors/*: allow granted by the built-in role, the deny takes precedence.
You can deny multiple monitor types in the same role by adding additional statements — for example, monitors/management/comparison/*: deny alongside the custom SQL deny.
Allowing only a specific monitor type
To invert the pattern and only allow a specific monitor type, deny the broad wildcard and then carve out an exception:
iam-role:
name: table-monitors-only
label: Table Monitors Only
description: Only allows table monitor management.
restrictions_summary: Denies all types of monitor access/management except for table monitors.
permissions:
monitors/management/*: deny
monitors/management/table/*: allowHere monitors/management/*: deny blocks all monitor types, and the more specific monitors/management/table/*: allow carves out an exception for table monitors. Users in this group can only work with table monitors while retaining all non-monitor-management permissions from the built-in role.
Managing audiences and API keys
Audiences don't have permissions of their own:
settings/notifications/access: view audiences, notification channels and routing rules.settings/notifications/edit: create, edit and delete notification channels and routing rules.
Creating or renaming an audience needs only general write access, and deleting one needs monitor edit permission (monitors/management/write).
Personal API keys give the same access as their owner has in the UI. settings/api/access and settings/api/edit let a user view and create personal API keys. The same permission also covers creating MCP server keys. Signing in to the MCP server with OAuth is controlled separately, by mcp/access (read-only tools) and mcp/edit (tools that make changes). Service account keys need settings/api/manage-tokens.
Controlling access to the AI agents
Access to Bayes, Monte Carlo's AI teammate, is governed by permissions under the ai-agents resource. Each Bayes skill has its own permission, so you can allow or deny each one separately:
ai-agents/troubleshooting/access(read) — ask Bayes to troubleshoot alerts and view its analyses.ai-agents/triage/access(read) — ask Bayes to triage alerts on demand.
Only troubleshooting and triage have their own permissions; Bayes' other skills are turned on or off for the whole account in Settings > AI Agents.
By default, every built-in role grants both permissions. Most do it with ai-agents/*: allow. mcd/viewer grants read-type AI agent permissions (ai-agents/read), which covers both, so Viewers can ask Bayes to troubleshoot and to triage alerts. See IAM Resources and Permissions for the full list.
These ai-agents permissions control who can use Bayes' skills. Controlling who can administer them — open the Settings > AI Agents page and change their configuration — is a separate resource, settings/ai-agents, covered in Restricting who administers AI Agent settings below.
Two things to keep in mind when planning restrictions:
- Denying
ai-agents/troubleshooting/accessremoves Bayes' troubleshooting entirely for that user — the run controls are disabled and existing analyses are hidden. - Denying
ai-agents/triage/accessonly blocks running triage on demand. Triage results (priority scores and reasoning) remain visible, because reading them is governed byalerts/access, not the triage permission. Automatic triage runs account-wide and is controlled in Settings > AI Agents, not by per-user permissions — see Configuring triage.
Blocking an AI agent
To take a Bayes skill away from a group of users, deny its permission. Follow the extend/modify approach and combine this custom role with a built-in role in an authorization group:
iam-role:
name: no-troubleshooting-agent
label: No Bayes troubleshooting
description: When combined with a built-in role, allows all standard access except asking Bayes to troubleshoot alerts or viewing its analyses.
restrictions_summary: Denies asking Bayes to troubleshoot alerts and viewing its analyses.
recommended_for: Users who should not have access to Bayes' troubleshooting.
permissions:
ai-agents/troubleshooting/access: denyTo block Bayes' triage instead, deny ai-agents/triage/access. To block all of Bayes' skills, deny the whole family with ai-agents/*: deny.
Limiting an AI agent to a specific team
Because the built-in roles grant AI agent access to everyone by default, restricting a Bayes skill to a single team is a matter of denying it everywhere else. Add the no-troubleshooting-agent role above to every authorization group except the team's group; the team keeps the default grant from its built-in role, and everyone else loses access.
A user's permissions resolve across all the authorization groups they belong to, and a more-specific deny always wins over a broader allow. So a user who is in the team's group and in any other group that carries the deny role will still be blocked. To keep a user's access, make sure they are not a member of any group that includes the deny role.
To also scope that team to their own assets — so they can only troubleshoot alerts on the tables they own — combine the grant with a domain restriction:
- Create a domain that defines the team's assets.
- In the authorization group editor for the team's group, under Access, choose Restrict to domains and select that domain.
- Leave the group's built-in role in place (which grants
ai-agents/*).
When Bayes troubleshoots an alert, it evaluates alert access against the alert's domain, so a domain-restricted group can only ask Bayes to troubleshoot alerts within its domains. This is the pattern to use when you want, for example, one team to troubleshoot only the alerts for the assets they are responsible for.
Restricting who administers AI Agent settings
The ai-agents permissions above control who can use Bayes' skills. A separate resource, settings/ai-agents, controls who can administer them — that is, who can open Settings > AI Agents and enable, disable, or reconfigure Bayes' troubleshooting and triage:
settings/ai-agents/access(read): open the Settings > AI Agents page and view the configuration.settings/ai-agents/edit(write): change settings on that page that don't control whether or how much Bayes runs, such as the Cost Agent's scope and tier. Per-domain triage overrides also needsettings/domains/edit.settings/ai-agents/manage-usage: turn Bayes' other skills on or off, choose their free or paid tiers, set when Bayes troubleshoots automatically, and set the account's AI agent usage limits. Among the built-in roles, only Account Owner has it.
Using a Bayes skill and administering its settings are deliberately kept separate — a user can hold one without the other:
| To control who may... | Deny... |
|---|---|
| ask Bayes to troubleshoot alerts | ai-agents/troubleshooting/access |
| ask Bayes to triage alerts on demand | ai-agents/triage/access |
| administer the settings for Bayes' skills | settings/ai-agents/access, settings/ai-agents/edit and settings/ai-agents/manage-usage |
To remove the Settings > AI Agents page and all of its controls from a group of users, deny both settings/ai-agents/access and settings/ai-agents/edit. Follow the extend/modify approach and combine this custom role with a built-in role in an authorization group:
iam-role:
name: no-ai-agent-settings-admin
label: No AI Agent Settings Admin
description: When combined with a built-in role, allows all standard access except administering AI Agent settings.
restrictions_summary: Denies opening and changing the Settings > AI Agents page.
recommended_for: Users who may use Bayes' skills but should not change how they are configured for the account.
permissions:
settings/ai-agents/access: deny
settings/ai-agents/edit: deny
settings/ai-agents/manage-usage: denyDeny the two permissions individually, not the
settings/ai-agents/*wildcard. Some built-in roles (Editor, for example) grantsettings/ai-agents/accessas a specific permission so their users can view the page, and a more specific grant always wins over a broader wildcard deny — so asettings/ai-agents/*: denyalone would leave the page readable for those roles. Denying each permission at the same level as it was granted removes both viewing and editing for every built-in role.
Because these denies are scoped to settings/ai-agents, they do not grant or deny any other settings capability. Users keep every other permission from their built-in role — including broad settings/edit if they have it — and lose only the AI Agents settings page. This is the point of the dedicated resource: previously the only lever over these controls was owner-level settings/edit, which also governs every other account setting, so there was no way to withhold AI Agent administration on its own.
Do not confuse
settings/ai-agents/*withsettings/agents/*. The names look almost identical but the resources are unrelated:settings/agents/*governs data collection agents (the agents that connect to your warehouses), whilesettings/ai-agents/*governs Bayes' skills (troubleshooting and triage). Denying the wrong one will not have the effect you intend.
Why this matters for automatic triage
Restricting settings administration is especially important for Bayes' triage. Denying ai-agents/triage/access only stops a user from running triage on demand — it has no effect on automatic triage, which is account-level and system-initiated: once enabled in Settings > AI Agents, a background service has Bayes triage every new alert, gated by the account settings and budget rather than by any individual user's permissions.
So the lever that controls whether automatic triage executes account-wide is the Settings > AI Agents toggle, governed by settings/ai-agents/manage-usage, not any per-user run permission. A user with that permission can turn automatic triage (and automated troubleshooting) on for the entire account, triggering background runs whose cost applies to the account and whose output they may not themselves be able to see. Only Account Owners have it by default, so check custom roles before granting settings/*.
Details and edge cases
What else ai-agents/* covers. Besides running the agents, ai-agents/* covers chatting with the AI agent anywhere it's available (ai-agents/access), agent memories (ai-agents/memories/access and ai-agents/memories/edit), agent posts to a domain's Teammate channel (ai-agents/channel-posts/create), and letting agents use custom MCP servers (ai-agents/mcp-servers/access). Adding or changing custom MCP servers needs settings/mcp-servers/edit.
Updated 3 days ago
