> ## Documentation Index
> Fetch the complete documentation index at: https://docs.murmur.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# role

> Catalog resource that defines a named set of permission rules — used by tenant-bindings to grant capabilities to users, groups, or service profiles.

A [role](/security/authorization) is a catalog resource that bundles [permissions](/security/permissions) under a reusable name. [Tenant bindings](/security/authorization) reference [roles](/security/authorization) to grant [permissions](/security/permissions) to users and [groups](/security/authorization).

## 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](/security/permissions) strings. Must be non-empty.                                                    |

## Permission format

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

| Form            | Meaning                                                        |
| --------------- | -------------------------------------------------------------- |
| `*`             | All [permissions](/security/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

```yaml theme={null}
name: agent-operator
description: "Full access to agents and workspaces"
permissions:
  - "agent.*"
  - "workspace.*"
```

```bash theme={null}
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

```yaml theme={null}
name: viewer
description: "Read and list access to all resources"
permissions:
  - "*.read"
  - "*.list"
```

```bash theme={null}
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

```yaml theme={null}
name: secret-manager
description: "Manage secrets only"
permissions:
  - "secret.read"
  - "secret.list"
  - "secret.create"
  - "secret.edit"
  - "secret.delete"
```

### Listing roles

```bash theme={null}
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

```bash theme={null}
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](/security/permissions) string to `permissions`.                                                             |
| `INVALID_ARGUMENT`    | `invalid permission "{perm}": must be "*", "{kind}.*", "*.{verb}", or "{kind}.{verb}"` | Fix the [permission](/security/permissions) 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](/security/permissions) 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](/security/authorization) that reference this [role](/security/authorization) before deleting it.   |

## Related

* [Authorization](/security/authorization) — how [roles](/security/authorization), [groups](/security/authorization), and [tenant bindings](/security/authorization) work together
* [Permissions](/security/permissions) — default [permissions](/security/permissions) and how to grant admin access
* [Catalog](/catalog/overview) — overview of all catalog resource types
* [`murmur set`](/cli/set) — CLI command for creating and updating catalog resources
* [`murmur get`](/cli/get) — CLI command for reading catalog resources