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

# tenant-binding

> Catalog resource that grants tenant-level permissions by binding a role to users, groups, or service profiles for authorization decisions.

A tenant-binding is a catalog resource that grants [permissions](/security/permissions) to users or [groups](/catalog/group) across your entire tenant. Each tenant-binding pairs a set of principals — GitHub logins and/or [groups](/catalog/group) — with either inline permissions or a named [role](/catalog/role).

Tenant-bindings with the `murmur-` name prefix are platform builtins and cannot be modified.

## Fields

| Name          | Type   | Required | Description                                                                                                          |
| ------------- | ------ | -------- | -------------------------------------------------------------------------------------------------------------------- |
| `name`        | string | yes      | Unique identifier. DNS label format: `[a-z][a-z0-9-]{0,62}`. The `murmur-` prefix is reserved for platform builtins. |
| `grant`       | object | yes      | Defines who gets what [permissions](/security/permissions). See [Grant fields](#grant-fields).                       |
| `description` | string | no       | Human-readable description shown in the dashboard. Maximum 1024 bytes.                                               |

## Grant fields

The `grant` object names the principals and the [permissions](/security/permissions) they receive.

| Name                       | Type      | Required    | Description                                                                                                                                            |
| -------------------------- | --------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `grant.groups`             | string\[] | conditional | [Group](/catalog/group) names in the same tenant. At least one of `groups` or `users` is required.                                                     |
| `grant.users`              | string\[] | conditional | GitHub logins. At least one of `groups` or `users` is required.                                                                                        |
| `grant.inline`             | object    | conditional | Inline [permissions](/security/permissions) list. Exactly one of `inline` or `role` is required.                                                       |
| `grant.inline.permissions` | string\[] | yes         | Permission strings in `{kind}.{verb}` format. Wildcards: `*` (all), `{kind}.*`, `*.{verb}`.                                                            |
| `grant.role`               | string    | conditional | Name of a [role](/catalog/role) in the same tenant. Exactly one of `inline` or `role` is required.                                                     |
| `grant.name_pattern`       | string    | no          | Restricts the grant to resources whose name matches this pattern. Supports variable substitution (`${provider}`, `${username}`) and trailing `*` glob. |

<Note>
  Permission strings use the format `{kind}.{verb}` where kind is a catalog resource kind and verb is one of `read`, `list`, `create`, `edit`, `delete`, `assume`, `encrypt`, or `endorse`. Use `*` for a full wildcard, `{kind}.*` for all verbs on a kind, or `*.{verb}` for one verb across all kinds.
</Note>

## Examples

### Grant a role to a group

```yaml theme={null}
name: engineers-workspace-admin
grant:
  groups:
    - platform-team
  role: workspace-admin
description: "Platform team gets workspace-admin role"
```

```bash theme={null}
cat <<'EOF' | murmur set tenant-binding engineers-workspace-admin
name: engineers-workspace-admin
grant:
  groups:
    - platform-team
  role: workspace-admin
description: "Platform team gets workspace-admin role"
EOF
```

### Grant inline permissions to specific users

```yaml theme={null}
name: oncall-read-access
grant:
  users:
    - alice
    - bob
  inline:
    permissions:
      - agent.read
      - agent.list
      - workspace.read
      - workspace.list
description: "On-call engineers can view agents and workspaces"
```

### Scope a grant with a name pattern

```yaml theme={null}
name: user-self-secrets
grant:
  groups:
    - all-members
  inline:
    permissions:
      - user-secret.read
      - user-secret.create
      - user-secret.edit
      - user-secret.delete
  name_pattern: "u/${provider}/${username}/*"
description: "Users manage their own secrets"
```

The `name_pattern` restricts this [tenant-binding](/catalog/tenant-binding) so each user can only access resources under their own namespace. `${provider}` and `${username}` are resolved from the caller's identity at evaluation time.

### Listing tenant-bindings

```bash theme={null}
murmur get tenant-binding
```

### Reading a single tenant-binding

```bash theme={null}
murmur get tenant-binding engineers-workspace-admin
```

## 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 a lowercase DNS label: starts with a letter, followed by up to 62 lowercase letters, digits, or hyphens.                                              |
| `INVALID_ARGUMENT` | `description exceeds 1024 byte limit`                                         | Shorten the `description` to 1024 bytes or fewer.                                                                                                         |
| `INVALID_ARGUMENT` | `grant is required`                                                           | Provide a `grant` block with principals and [permissions](/security/permissions).                                                                         |
| `INVALID_ARGUMENT` | `grant must specify at least one group or user`                               | Add at least one entry to `grant.groups` or `grant.users`.                                                                                                |
| `INVALID_ARGUMENT` | `grant must specify inline permissions or a role reference`                   | Set exactly one of `grant.inline` or `grant.role`.                                                                                                        |
| `INVALID_ARGUMENT` | `grant role reference must be non-empty`                                      | The `grant.role` field is present but empty. Provide a [role](/catalog/role) name.                                                                        |
| `INVALID_ARGUMENT` | `grant permissions must be non-empty`                                         | The `grant.inline.permissions` list is empty. Add at least one permission string.                                                                         |
| `INVALID_ARGUMENT` | `invalid permission: must be "*", "{kind}.*", "*.{verb}", or "{kind}.{verb}"` | Fix the permission string format.                                                                                                                         |
| `INVALID_ARGUMENT` | `invalid permission: unknown kind`                                            | The kind portion of the permission string does not match a registered catalog kind.                                                                       |
| `INVALID_ARGUMENT` | `invalid permission: unknown verb`                                            | The verb portion is not one of `read`, `list`, `create`, `edit`, `delete`, `assume`, `encrypt`, `endorse`.                                                |
| `INVALID_ARGUMENT` | `duplicate permission`                                                        | Remove the duplicated permission string from the list.                                                                                                    |
| `INVALID_ARGUMENT` | `"*" makes other permissions redundant`                                       | A full wildcard `*` is present alongside other [permissions](/security/permissions). Use `*` alone or list specific [permissions](/security/permissions). |
| `INVALID_ARGUMENT` | `permission is subsumed by wildcard`                                          | A specific permission like `agent.read` is redundant because `agent.*` or `*.read` is already in the list. Remove the narrower entry.                     |
| `INVALID_ARGUMENT` | `group "..." does not exist`                                                  | The referenced [group](/catalog/group) does not exist in the tenant. Create it first with `murmur set group`.                                             |
| `INVALID_ARGUMENT` | `role "..." does not exist`                                                   | The referenced [role](/catalog/role) does not exist in the tenant. Create it first with `murmur set role`.                                                |

## Related

* [Permissions](/security/permissions) — how permission strings work
* [Authorization](/security/authorization) — how grants are evaluated
* [role](/catalog/role) — named permission bundle referenced by `grant.role`
* [group](/catalog/group) — named principal set referenced by `grant.groups`
* [`murmur set`](/cli/set) — CLI command for creating and updating catalog resources
* [`murmur get`](/cli/get) — CLI command for reading catalog resources