Role

A role is a named, organization-scoped bundle of permissions. Users hold zero or more roles; their effective permission set is the deduplicated union across all assigned roles.

Every organization is seeded with a single system role, Admin. Admin is locked (it cannot be renamed, edited, or deleted) and always resolves to every permission in the catalog, including permissions added in future releases, regardless of what is stored in its permissions field.

Field	Type	Behavior	Description
name	string	OUTPUT_ONLY	Resource name (roles/{role_id})
display_name	string		Human-readable name shown in the UI (e.g. Integrations Owner)
description	string		Optional description of the role
permissions	Permission[]		Permissions held by this role. Reads are implicit, so the catalog contains only :write and :run keys. Empty for the system Admin role, whose effective set is computed server-side.
system	boolean	OUTPUT_ONLY	True on the single seeded system role (Admin). Uneditable and undeletable.
is_default	boolean	OUTPUT_ONLY	True on exactly one role per org: the default assigned to new members. Change it with SetDefaultRole.
create_time	timestamp	OUTPUT_ONLY	When the role was created
update_time	timestamp	OUTPUT_ONLY	When the role was last modified
delete_time	timestamp	OUTPUT_ONLY	When the role was soft-deleted (null if active)

Example

{
  "name": "roles/integrations-owner",
  "displayName": "Integrations Owner",
  "description": "Manages connections and integrations",
  "permissions": ["INTEGRATIONS_WRITE"],
  "system": false,
  "isDefault": false,
  "createTime": "2024-06-15T14:30:00Z",
  "updateTime": "2024-06-15T14:30:00Z"
}

Permission

The permission catalog is fixed and owned by the platform; organizations compose these values into roles but cannot invent new keys. Each value follows a resource:action shape. There are no :read keys, reads are implicit for any authenticated organization member.

A role’s stored permissions array carries the enum names below. The no- privilege-escalation rule applies on every mutation: an actor may only grant permissions that are a subset of their own effective permissions.

Value	Meaning
PERMISSION_UNSPECIFIED	Default zero value, never a valid grant
OBSERVABILITY_WRITE	Edit the observability model (services, SLOs, signals, providers) and configure its Expert agents
OBSERVABILITY_RUN	Trigger SLO evaluations and recreate observability Expert sessions
ISSUES_WRITE	Manage issues, notification policies, and autofix configuration
KNOWLEDGE_WRITE	Edit the knowledge base (runbooks, flows, notes, customer catalog)
INVESTIGATIONS_WRITE	Edit investigation metadata and purge investigations
INVESTIGATIONS_RUN	Start new investigation sessions
AGENTS_WRITE	Create, edit, and delete custom workflow agents
AGENTS_RUN	Start and stop custom agent runs
INTEGRATIONS_WRITE	Manage connections, MCP servers, transports, ingest, and skills
CHANGE_MONITOR_WRITE	Manage change-monitor configuration and its agent
MEMBERS_WRITE	Assign roles to organization members
BILLING_WRITE	Change plan and payment methods
ROLES_WRITE	Create, edit, and delete roles and their permission grants