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: deny

How 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.

The permission controlling sampling data access is monitors/data-sampling/access. Currently, only mcd/owner and mcd/domains-manager grant this permission via their monitors/*: allow wildcard. The mcd/editor role explicitly denies it.

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: allow

Note: 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 mcd/owner or mcd/domains-manager:

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: deny

Limiting 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:

1. Create a domain that defines the subset of data you want to allow.
2. In the authorization group editor, under Access, choose Restrict to domains and select your domain.
3. Under Roles, include both your desired built-in role and the allow-data-sampling role 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).

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.

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.

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/*: deny

How 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/*: allow

Here 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.

Controlling access to the AI agents

Access to Monte Carlo's AI agents is governed by permissions under the ai-agents resource:

• ai-agents/troubleshooting/access (read) — run the Troubleshooting Agent on alerts and view its analyses.
• ai-agents/triage/edit (write) — run the Triage Agent on demand to triage and update alerts.

By default, every built-in role grants these permissions via ai-agents/*: allow, except mcd/viewer, which grants only read-type AI agent permissions (ai-agents/read). As a result, Viewers can use the Troubleshooting Agent but not run the Triage Agent, which is a write operation. See IAM Resources and Permissions for the full list.

These ai-agents permissions control who can run the agents. Controlling who can administer the agents — 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/access removes the Troubleshooting Agent entirely for that user — the run controls are disabled and existing analyses are hidden.
• Denying ai-agents/triage/edit only blocks running triage on demand. Triage results (priority scores and reasoning) remain visible, because reading them is governed by alerts/access, not the agent permission. Automatic triage runs account-wide and is controlled in Settings > AI Agents, not by per-user permissions — see Configuring the Triage Agent.

Blocking an AI agent

To take an agent 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 Troubleshooting Agent
  description: When combined with a built-in role, allows all standard access except running the Troubleshooting Agent or viewing its analyses.
  restrictions_summary: Denies running the Troubleshooting Agent and viewing its analyses.
  recommended_for: Users who should not have access to the Troubleshooting Agent.
  permissions:
    ai-agents/troubleshooting/access: deny

To block the Triage Agent instead, deny ai-agents/triage/edit. To block all AI agents, 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 an agent 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.

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:

1. Create a domain that defines the team's assets.
2. In the authorization group editor for the team's group, under Access, choose Restrict to domains and select that domain.
3. Leave the group's built-in role in place (which grants ai-agents/*).

The Troubleshooting Agent evaluates alert access against the alert's domain, so a domain-restricted group can only run it on 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 run the agents. A separate resource, settings/ai-agents, controls who can administer them — that is, who can open Settings > AI Agents and enable, disable, or reconfigure the Troubleshooting and Triage agents:

• settings/ai-agents/access (read) — open the Settings > AI Agents page and view the agent configuration.
• settings/ai-agents/edit (write) — change any setting on that page: the feature toggles, triage usage restrictions and thresholds, automated troubleshooting, and per-domain overrides.

Running an agent and administering its settings are deliberately kept separate — a user can hold one without the other:

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 the AI agents but should not change how they are configured for the account.
  permissions:
    settings/ai-agents/access: deny
    settings/ai-agents/edit: deny

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.

Why this matters for automatic triage

Restricting settings administration is especially important for the Triage Agent. Denying ai-agents/triage/edit 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 runs it on 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/edit — not any per-user run permission. A user who can edit that page 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. Gating settings/ai-agents/edit is how you control who can make that call.