Skip to main content

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.

A tenant-binding is a catalog resource that grants permissions to users or groups across your entire tenant. Each tenant-binding pairs a set of principals — GitHub logins and/or groups — with either inline permissions or a named role. Tenant-bindings with the murmur- name prefix are platform builtins and cannot be modified.

​
Fields

NameTypeRequiredDescription
namestringyesUnique identifier. DNS label format: [a-z][a-z0-9-]{0,62}. The murmur- prefix is reserved for platform builtins.
grantobjectyesDefines who gets what permissions. See Grant fields.
descriptionstringnoHuman-readable description shown in the dashboard. Maximum 1024 bytes.

​
Grant fields

The grant object names the principals and the permissions they receive.
NameTypeRequiredDescription
grant.groupsstring[]conditionalGroup names in the same tenant. At least one of groups or users is required.
grant.usersstring[]conditionalGitHub logins. At least one of groups or users is required.
grant.inlineobjectconditionalInline permissions list. Exactly one of inline or role is required.
grant.inline.permissionsstring[]yesPermission strings in {kind}.{verb} format. Wildcards: * (all), {kind}.*, *.{verb}.
grant.rolestringconditionalName of a role in the same tenant. Exactly one of inline or role is required.
grant.name_patternstringnoRestricts the grant to resources whose name matches this pattern. Supports variable substitution (${provider}, ${username}) and trailing * glob.
Permission strings use the format {kind}.{verb} where kind is a catalog resource kind and verb is one of read, list, create, edit, delete, or assume. Use * for a full wildcard, {kind}.* for all verbs on a kind, or *.{verb} for one verb across all kinds.

​
Examples

​
Grant a role to a group

name: engineers-workspace-admin
grant:
  groups:
    - platform-team
  role: workspace-admin
description: "Platform team gets workspace-admin role"

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

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

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

murmur get tenant-binding

​
Reading a single tenant-binding

murmur get tenant-binding engineers-workspace-admin

​
Errors

CodeMeaningWhat to do
INVALID_ARGUMENTname is requiredProvide a name field.
INVALID_ARGUMENTname 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_ARGUMENTdescription exceeds 1024 byte limitShorten the description to 1024 bytes or fewer.
INVALID_ARGUMENTgrant is requiredProvide a grant block with principals and permissions.
INVALID_ARGUMENTgrant must specify at least one group or userAdd at least one entry to grant.groups or grant.users.
INVALID_ARGUMENTgrant must specify inline permissions or a role referenceSet exactly one of grant.inline or grant.role.
INVALID_ARGUMENTgrant role reference must be non-emptyThe grant.role field is present but empty. Provide a role name.
INVALID_ARGUMENTgrant permissions must be non-emptyThe grant.inline.permissions list is empty. Add at least one permission string.
INVALID_ARGUMENTinvalid permission: must be "*", "{kind}.*", "*.{verb}", or "{kind}.{verb}"Fix the permission string format.
INVALID_ARGUMENTinvalid permission: unknown kindThe kind portion of the permission string does not match a registered catalog kind.
INVALID_ARGUMENTinvalid permission: unknown verbThe verb portion is not one of read, list, create, edit, delete, assume.
INVALID_ARGUMENTduplicate permissionRemove the duplicated permission string from the list.
INVALID_ARGUMENT"*" makes other permissions redundantA full wildcard * is present alongside other permissions. Use * alone or list specific permissions.
INVALID_ARGUMENTpermission is subsumed by wildcardA specific permission like agent.read is redundant because agent.* or *.read is already in the list. Remove the narrower entry.
INVALID_ARGUMENTgroup "..." does not existThe referenced group does not exist in the tenant. Create it first with murmur set group.
INVALID_ARGUMENTrole "..." does not existThe referenced role does not exist in the tenant. Create it first with murmur set role.
  • Permissions — how permission strings work
  • Authorization — how grants are evaluated
  • role — named permission bundle referenced by grant.role
  • group — named principal set referenced by grant.groups
  • murmur set — CLI command for creating and updating catalog resources
  • murmur get — CLI command for reading catalog resources