role

A role is a catalog resource that bundles permissions under a reusable name. Tenant bindings reference roles to grant permissions to users and groups.

Fields

Name	Type	Required	Description
`name`	string	yes	Unique identifier. DNS label format: `[a-z][a-z0-9-]{0,62}`. Names starting with `murmur-` are reserved for platform builtins.
`description`	string	no	Human-readable description shown in the dashboard. Maximum 1024 bytes.
`permissions`	string[]	yes	One or more permission strings. Must be non-empty.

Permission format

Each entry in permissions is a string in one of four forms:

Form	Meaning
`*`	All permissions on all catalog kinds.
`{kind}.*`	All verbs on the specified kind.
`*.{verb}`	The specified verb on all kinds.
`{kind}.{verb}`	A single verb on a single kind.

Kinds

A {kind} is any catalog resource type: recipe, image, environment, pool-config, service-profile, repo-config, agent-persona, agent, flight, change-request, workspace, placement, machine-type, disk-type, secret, alias, role, group, tenant-binding, user, user-secret.

Verbs

Verb	Description
`read`	Get a resource.
`list`	List resources of a kind.
`create`	Create a new resource.
`edit`	Mutate an existing resource.
`delete`	Delete a resource.
`assume`	Use a resource as a runtime credential.
`encrypt`	Encrypt tenant secret material. Distinct from `read` so a tenant-wide read grant cannot also encrypt.
`endorse`	Add or remove an advisory thumbs-up on a change-request. Never authorizes a write.

Examples

Create a role with full agent access

name: agent-operator
description: "Full access to agents and workspaces"
permissions:
  - "agent.*"
  - "workspace.*"

cat <<'EOF' | murmur set role agent-operator
name: agent-operator
description: "Full access to agents and workspaces"
permissions:
  - "agent.*"
  - "workspace.*"
EOF

Create a read-only role

name: viewer
description: "Read and list access to all resources"
permissions:
  - "*.read"
  - "*.list"

cat <<'EOF' | murmur set role viewer
name: viewer
description: "Read and list access to all resources"
permissions:
  - "*.read"
  - "*.list"
EOF

Create a role scoped to secrets

name: secret-manager
description: "Manage secrets only"
permissions:
  - "secret.read"
  - "secret.list"
  - "secret.create"
  - "secret.edit"
  - "secret.delete"

Listing roles

murmur get role

NAME              DESCRIPTION
murmur-admin      Platform builtin — full access
murmur-member     Platform builtin — default member access
agent-operator    Full access to agents and workspaces
viewer            Read and list access to all resources

Reading a single role

murmur get role agent-operator

Errors

Code	Meaning	What to do
`INVALID_ARGUMENT`	`name is required`	Provide a `name` field.
`INVALID_ARGUMENT`	`name must match [a-z][a-z0-9-]{0,62}`	Use only lowercase letters, digits, and hyphens. Must start with a letter.
`INVALID_ARGUMENT`	`description exceeds 1024 byte limit`	Shorten the `description` to 1024 bytes or fewer.
`INVALID_ARGUMENT`	`permissions must be non-empty`	Add at least one permission string to `permissions`.
`INVALID_ARGUMENT`	`invalid permission "{perm}": must be "", "{kind}.", "*.{verb}", or "{kind}.{verb}"`	Fix the permission string to use a valid form.
`INVALID_ARGUMENT`	`invalid permission "{perm}": unknown kind "{kind}"`	Use a valid catalog kind name. See the kinds list above.
`INVALID_ARGUMENT`	`invalid permission "{perm}": unknown verb "{verb}"`	Use a valid verb: `read`, `list`, `create`, `edit`, `delete`, `assume`, `encrypt`, or `endorse`.
`INVALID_ARGUMENT`	`duplicate permission "{perm}"`	Remove the duplicate entry from `permissions`.
`INVALID_ARGUMENT`	`"*" makes other permissions redundant`	When using `*`, it must be the only entry in `permissions`.
`INVALID_ARGUMENT`	`"{perm}" is subsumed by "{wildcard}"`	A more specific permission is redundant because a broader wildcard already covers it. Remove the narrower entry.
`FAILED_PRECONDITION`	`cannot delete role "{name}": referenced by tenant-binding: {bindings}`	Remove or update the tenant bindings that reference this role before deleting it.

Authorization — how roles, groups, and tenant bindings work together
Permissions — default permissions and how to grant admin access
Catalog — overview of all catalog resource types
murmur set — CLI command for creating and updating catalog resources
murmur get — CLI command for reading catalog resources

Getting Started

Core Concepts

Guides

Fields

Permission format

Kinds

Verbs

Examples

Create a role with full agent access

Create a read-only role

Create a role scoped to secrets

Listing roles

Reading a single role

Errors

​Fields

​Permission format

​Kinds

​Verbs

​Examples

​Create a role with full agent access

​Create a read-only role

​Create a role scoped to secrets

​Listing roles

​Reading a single role

​Errors

​Related

Fields

Permission format

Kinds

Verbs

Examples

Create a role with full agent access

Create a read-only role

Create a role scoped to secrets

Listing roles

Reading a single role

Errors

Related