Skip to main content
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

NameTypeRequiredDescription
namestringyesUnique identifier. DNS label format: [a-z][a-z0-9-]{0,62}. Names starting with murmur- are reserved for platform builtins.
descriptionstringnoHuman-readable description shown in the dashboard. Maximum 1024 bytes.
permissionsstring[]yesOne or more permission strings. Must be non-empty.

​
Permission format

Each entry in permissions is a string in one of four forms:
FormMeaning
*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

VerbDescription
readGet a resource.
listList resources of a kind.
createCreate a new resource.
editMutate an existing resource.
deleteDelete a resource.
assumeUse a resource as a runtime credential.
encryptEncrypt tenant secret material. Distinct from read so a tenant-wide read grant cannot also encrypt.
endorseAdd 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

CodeMeaningWhat to do
INVALID_ARGUMENTname is requiredProvide a name field.
INVALID_ARGUMENTname must match [a-z][a-z0-9-]{0,62}Use only lowercase letters, digits, and hyphens. Must start with a letter.
INVALID_ARGUMENTdescription exceeds 1024 byte limitShorten the description to 1024 bytes or fewer.
INVALID_ARGUMENTpermissions must be non-emptyAdd at least one permission string to permissions.
INVALID_ARGUMENTinvalid permission "{perm}": must be "*", "{kind}.*", "*.{verb}", or "{kind}.{verb}"Fix the permission string to use a valid form.
INVALID_ARGUMENTinvalid permission "{perm}": unknown kind "{kind}"Use a valid catalog kind name. See the kinds list above.
INVALID_ARGUMENTinvalid permission "{perm}": unknown verb "{verb}"Use a valid verb: read, list, create, edit, delete, assume, encrypt, or endorse.
INVALID_ARGUMENTduplicate permission "{perm}"Remove the duplicate entry from permissions.
INVALID_ARGUMENT"*" makes other permissions redundantWhen 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_PRECONDITIONcannot delete role "{name}": referenced by tenant-binding: {bindings}Remove or update the tenant bindings that reference this role before deleting it.