Skip to main content
Authorization determines which resources you can discover, read, create, and manage in your tenant. Roles collect permissions, groups collect principals, and tenant-bindings connect those principals to permissions across the tenant. Resource grants add permissions on individual resources and their contents.

​
Default access

GitHub organization owners hold * through the built-in murmur-org-admin-root tenant-binding. Other members can create workspaces, spawn their own agents in workspaces they can use, and manage their existing agents. Members read a workspace’s configuration through its grants, not through a tenant-wide workspace.read default. They see other people’s agents only where they also have access to the containing workspace. Built-in tenant-bindings also provide:
  • Proposals: members and service profiles hold change-request.create, change-request.read, and change-request.endorse through murmur-shared-floor. The same grant extends live to their running agents. Reading a proposed value and endorsing still require access to the target; approval requires authority to write the target.
  • Shared catalog reads: murmur-shared-floor also grants agent-persona.read, machine-type.read, and knowledge.*, including live extension to running agents. Access to workspace-scoped resources additionally requires workspace.use.
  • Attachments: murmur-shared-floor also grants attachment.create to members and service profiles, extended live to their running agents: once an owner leaves the org, their agents can no longer stage files. Staging a file does not authorize the spawn or follow-up that attaches it.
  • Peer reads: murmur-agent-peer-read lets a running agent read its owner’s other agents in the same workspace. Additional tenant-bindings can grant broader access.
See the permission reference for the capability inventory and defaults.

​
Permission model

A permission has the form {kind}.{verb}, such as agent.read or workspace.use. The role reference lists valid kinds and verbs. read covers both direct reads and visibility in listings. list is not an authorization permission: explicit grants such as agent.list and *.list are rejected.

​
Wildcards

Wildcards cover new kinds and verbs as they are added. A name_pattern still confines a wildcard grant to matching resource names. Reading workspace-scoped resources additionally requires workspace.use; *.read alone does not supply it.

​
Resource and workspace grants

Grants are additive. A resource grant does not remove permissions conferred by a tenant-binding. A workspace carries grants that apply to the workspace itself and resources named under it. For example, a grant using the built-in murmur-workspace-manager role confers management of that workspace, its scoped catalog resources, and all agents in it. The murmur-workspace-user role supplies workspace.read, workspace.use, and reads of its scoped catalog resources. It does not itself grant agent.create or agent.read. Scoped catalog names use {workspace}/{name} for recipes, images, environments, agent personas, canned responses, knowledge, tool-link policies, and secrets. Access requires both the kind permission and workspace.use on the containing workspace. A bare catalog name is tenant-level; a workspace grant does not generally authorize it. Resources explicitly admitted for use there can receive that workspace’s extended runtime read grants; see workspace_use. Reading or editing the workspace record itself requires workspace.read or workspace.edit, respectively, not a separate workspace.use check. An existing agent’s owner and its own runtime retain their workspace access exemption for that agent and its descendants. A new spawn requires workspace.use. Service-profile grants control access to that service profile, such as permission to assume it. They do not define what the service profile may do elsewhere. That authority comes from tenant-bindings and grants on the resources it accesses.

​
Listing

Catalog listings return entries authorized by read, including any applicable resource grants and workspace access. No readable entries means an empty successful listing. Filters, name prefixes, and workspace selectors narrow results; they confer no permissions. Agent discovery has an additional distinction: listings, tree views, live tree updates, and run history use agent.read from tenant-bindings, runtime self-grants, or grants on the containing workspace. Each entry also needs workspace.use, except for the owner and the runtime’s own subtree. Listings do not check service-account grants or a separate service-account view restriction. Grants attached to an individual agent, or inherited from a parent agent, authorize direct access by name but do not make it discoverable. Give discoverers agent.read through a tenant-binding or workspace grant. A grant’s name_pattern limits which names appear.

​
Name patterns

A grant’s name_pattern matches the target resource’s catalog name. No pattern means unrestricted names; a trailing * matches a prefix; otherwise the match is exact. There are no other glob operators. If a named variable has no value, that pattern does not match. For example, ${provider}/${username}/* resolves to github_oauth/alice/* for developer alice. It is a login-based match, not an additional provider-subject-ID match.

​
Runtime extension

extend_to_runtime_agents: true extends a grant from its matched principal to running agents that act as that principal. It is evaluated on each request, not copied at spawn. Editing the grant, changing membership, or deleting the service profile changes what subsequent requests receive through that grant. The acting identity is the recorded service profile, including a borrowed one, or otherwise the developer owner. Its current principals and memberships must match, and the pattern resolves against that identity. Extension applies to tenant-bindings and grants on the running agent’s own workspace. Other resource grants do not extend. A workspace grant extends only within that workspace and to reads of tenant-level resources admitted for use there.