IAM Roles and Permissions

MeshAgent IAM controls access to project resources. It answers four questions:

Who is requesting access: a user, group, agent, service account, or userset.
What they are accessing: a project, room, repository, feed, secret, service account, or other project resource.
Which role they have on that resource.
Which room API scope a participant token carries after access is granted.

Use the smallest role or scope that lets the subject do its job.

Principals

Principal type	Description
`user`	A human project member.
`group`	A group of users. Group access applies through the group’s members.
`agent`	A managed agent principal.
`service_account`	A non-human identity used by services, jobs, API keys, and automation.
`userset`	A reference to another resource relation, such as all project members.

Resources

Resource type	Description
`project`	The top-level project boundary. Project roles can grant project-wide create, inventory, manage, billing, LLM proxy, and group-management access.
`room`	A room and its room-scoped APIs.
`agent`	A managed agent resource. Managed agent resource policies are not set through the generic IAM policy API; agent run-as and project agent roles control this surface.
`group`	A group and its membership.
`repository`	A project image repository.
`feed`	A feed and its publish/subscribe operations.
`secret`	A user secret that can be proxied to a service account.
`service_account`	A service account and the credentials or run-as permissions attached to it.

Project Roles

Project roles apply at the project level. The user who creates a project becomes its owner and automatically inherits admin access. Admins inherit user_profile_editor along with the other administrative project permissions. developer inherits a focused operational subset and does not include user_profile_editor. Direct, narrower roles can also be granted independently.

Role	Controls	What it allows
`owner`	Project ownership	Owns the project and implicitly has project admin access.
`member`	Project membership	Lets the subject act as a project member and be targeted by project-member access.
`agent`	Project agent identity	Marks an agent as belonging to the project so it can be targeted by project-agent access.
`service_account`	Project service account identity	Marks a service account as belonging to the project so it can be targeted by project service-account access.
`admin`	Full project administration	Grants administrative project access and all project roles that are not core membership roles.
`developer`	Operational project access	Grants developer access, including inventory/manage access for rooms, agents, repositories, feeds, service inventory, mailbox inventory, route inventory, scheduled task inventory, feed subscription inventory, LLM logger inventory, usage reporting, service account creation/inventory, and participant token creation.
`room_creator`	Room creation	Create rooms.
`room_inventory`	Room inventory	List and inspect room inventory across the project.
`room_manager`	Room management	Manage rooms across the project.
`session_inventory`	Session inventory	Inspect project session inventory.
`agent_creator`	Managed agent creation	Create managed agents.
`agent_inventory`	Managed agent inventory	List and inspect managed agent inventory.
`agent_manager`	Managed agent management	Manage managed agents.
`repository_creator`	Repository creation	Create project repositories.
`repository_inventory`	Repository inventory	List and inspect repositories.
`repository_manager`	Repository management	Manage repositories.
`feed_creator`	Feed creation	Create feeds.
`feed_inventory`	Feed inventory	List and inspect feeds.
`feed_manager`	Feed management	Manage feeds.
`oauth_client_creator`	OAuth client creation	Create project OAuth clients.
`oauth_client_inventory`	OAuth client inventory	List and inspect project OAuth clients.
`oauth_client_manager`	OAuth client management	Manage project OAuth clients.
`api_key_creator`	API key creation	Create API keys.
`api_key_inventory`	API key inventory	List and inspect API keys.
`api_key_manager`	API key management	Manage API keys.
`service_creator`	Service creation	Create deployed services.
`service_inventory`	Service inventory	List and inspect deployed services.
`service_manager`	Service management	Manage deployed services.
`service_account_creator`	Service account creation	Create service accounts.
`service_account_inventory`	Service account inventory	List and inspect service accounts.
`service_account_manager`	Service account management	Manage service accounts.
`participant_token_creator`	Participant token impersonation	Allow a service account to request a participant token for another user or service account by email. The target subject’s room or agent permissions still apply.
`mailbox_creator`	Mailbox creation	Create mailboxes.
`mailbox_inventory`	Mailbox inventory	List and inspect mailboxes.
`mailbox_manager`	Mailbox management	Manage mailboxes.
`route_creator`	Route creation	Create routes.
`route_inventory`	Route inventory	List and inspect routes.
`route_manager`	Route management	Manage routes.
`scheduled_task_creator`	Scheduled task creation	Create scheduled tasks.
`scheduled_task_inventory`	Scheduled task inventory	List and inspect scheduled tasks.
`scheduled_task_manager`	Scheduled task management	Manage scheduled tasks.
`feed_subscription_creator`	Feed subscription creation	Create feed subscriptions.
`feed_subscription_inventory`	Feed subscription inventory	List and inspect feed subscriptions.
`feed_subscription_manager`	Feed subscription management	Manage feed subscriptions.
`llm_logger_creator`	LLM logger creation	Create LLM loggers.
`llm_logger_inventory`	LLM logger inventory	List and inspect LLM loggers.
`llm_logger_manager`	LLM logger management	Manage LLM loggers.
`llm_proxy_user`	Project LLM proxy use	Use the project LLM proxy and related OAuth proxy surfaces.
`usage_reporter`	Usage reporting	Report or query project usage.
`billing_manager`	Billing	Manage project billing.
`group_manager`	Groups	Manage project groups.
`user_profile_editor`	User profiles	Edit project-local names, metadata, and annotations for users who belong to the project, including your own overrides. Inherited by project owners and admins.

Project membership APIs accept a roles list. The server normalizes project membership to include member and expands inherited admin and developer roles. Older member records and Studio convenience settings map to roles like this:

Setting	Expanded role effect
`is_admin`	Grants `admin` plus every non-core creator, inventory, manager, billing, usage, group, LLM proxy, and user profile editor role.
`is_developer`	Grants `developer`, room/agent/repository/feed manager roles, developer inventory roles, `service_account_creator`, `service_account_inventory`, `participant_token_creator`, and `usage_reporter`. The `developer` relation also qualifies for LLM proxy use in access checks.
`can_create_rooms`	Grants `room_creator`, `mailbox_creator`, `route_creator`, and `scheduled_task_creator`.
`can_create_agents`	Grants `agent_creator`.
`can_use_llm_proxy`	Grants the direct `llm_proxy_user` role.

User profile permissions

Users can edit their own global names and metadata with profile:write. Project roles cannot edit global account defaults. Global annotations and editing other accounts require sysadmin endpoints, the OAuth sysadmin scope, and registered sysadmin membership. Editing any project-local user profile, including your own, requires user_profile_editor, a token covering the project with projects:iam.write, and target membership. The legacy admin scope is accepted in place of projects:iam.write. Owners and admins inherit the editor permission; developers and ordinary members need an explicit grant. Project profile reads and listings accept --view project|user|merged (default merged). All views require project access; project returns stored overrides, user returns global defaults, and merged applies overrides to defaults. Metadata and annotations merge by key.

# Edit your shared defaults regardless of the active project.
meshagent user update me --global --first-name Alice --metadata '{"theme":"dark"}'

# Edit only this project's user record; requires user_profile_editor.
meshagent user update "$USER_ID" --project-id "$PROJECT_ID" \
  --metadata '{"department":"support"}' --annotations '{"team":"support"}'
meshagent user get "$USER_ID" --project-id "$PROJECT_ID" --view project -o json
meshagent user list --project-id "$PROJECT_ID" --view merged
meshagent user update "$USER_ID" --project-id "$PROJECT_ID" --inherit first_name

# Platform administration; requires sysadmin scope and membership.
meshagent sysadmin user list --filter alice -o json
meshagent sysadmin user get "$USER_ID"
meshagent sysadmin user update "$USER_ID" --annotations '{"verified":"yes"}'

CLI profile reads and updates use the selected project, including MESHAGENT_PROJECT_ID or the active project. Use --global for personal account defaults. Without a project, ordinary profile commands address only your own global profile. Supplied maps replace the selected layer’s map; {} clears it. --inherit removes a project override and can be repeated. Annotations require string values. Global annotations can only be changed with sysadmin user update. Sysadmin CLI commands require a login token containing sysadmin. For a dedicated administrator login, use MESHAGENT_OAUTH_SCOPES='profile:read profile:write sysadmin' meshagent auth login. Registered sysadmin membership is still required; adding the scope does not grant that membership. See User profiles in the REST API for SDK examples, or Editing user profiles in Accounts for the app workflow.

Room, Agent, and Repository Roles

These roles apply to resource policies for rooms and repositories. They also describe the effective role set used for room and agent access decisions.

Role	Controls	What it allows
`viewer`	Read-only resource access	View or connect to the resource with limited API scope.
`operator`	Standard resource operation	Operate the resource with the standard user API scope.
`developer`	Developer resource operation	Operate the resource with the agent-default API scope and developer capabilities.
`admin`	Resource administration	Manage the resource and receive full room API scope where applicable.
`list`	Resource discoverability	Include the resource in listings without granting full resource use by itself.

For rooms, viewer, operator, developer, and admin map to room API scopes:

Resource role	Room API scope
`viewer`	Livekit access, read-only messaging list access, and service listing.
`operator`	`ApiScope.user_default()`.
`developer`	`ApiScope.agent_default(tunnels=True)` with admin config disabled.
`admin`	`ApiScope.full()`.

Group Roles

Role	Controls	What it allows
`member`	Group membership	Makes the subject a member of the group. Group membership can be used anywhere the group has access.
`manager`	Group management	Manage the group and its membership. Project `group_manager` also grants group-management access.

Feed Roles

Role	Controls	What it allows
`reader`	Feed read access	Read feed items.
`subscriber`	Feed subscriptions	Subscribe to the feed and read feed items.
`publisher`	Feed publishing	Publish feed items and read feed items.
`manager`	Feed management	Manage the feed, publish, subscribe, and read.
`list`	Feed discoverability	Include the feed in listings without granting publish or manage by itself.

Secret Roles

Role	Controls	What it allows
`use_proxy`	User secret proxying	Allows a service account to use the proxied value of a user secret.

Service Account Roles

Role	Controls	What it allows
`list`	Service account listing	List or discover the service account.
`run_service_as`	Service run identity	Run a service or managed agent as the service account.
`secret_accessor`	Service account secret access	Access service account secret versions.
`secret_manager`	Service account secret management	Manage service account secrets.
`secret_list`	Service account secret listing	List service account secrets.
`use_proxy_secrets`	Proxy secret use	Use proxied secrets attached to the service account.

OAuth Scopes

OAuth scopes are token scopes, not OpenFGA resource roles. MeshAgent accepts the current scope names below for OAuth access tokens. Project and room wildcard scopes (project/*, room/*) still identify the project or room boundary for token checks.

Scope group	Scopes
Profile	`profile:read`, `profile:write`
Project and room boundary	`project/`, `room/`
Users	`users:create`, `users:read`, `users:update`, `users:delete`
Projects	`projects:read`, `projects:update`, `projects:iam.read`, `projects:iam.write`, `projects:billing.read`, `projects:billing.write`
Rooms	`rooms:create`, `rooms:read`, `rooms:connect`, `rooms:update`, `rooms:delete`
Managed agents	`agents:create`, `agents:read`, `agents:update`, `agents:delete`, `agents:run`, `agents:sessions.read`
Mailboxes	`mailboxes:create`, `mailboxes:read`, `mailboxes:update`, `mailboxes:delete`
Routes	`routes:create`, `routes:read`, `routes:update`, `routes:delete`
Scheduled tasks	`scheduledTasks:create`, `scheduledTasks:read`, `scheduledTasks:update`, `scheduledTasks:delete`
Services	`services:create`, `services:read`, `services:update`, `services:delete`
Repositories	`repositories:create`, `repositories:read`, `repositories:update`, `repositories:delete`
API keys	`apiKeys:create`, `apiKeys:read`, `apiKeys:delete`
Service accounts	`serviceAccounts:create`, `serviceAccounts:read`, `serviceAccounts:update`, `serviceAccounts:delete`
OAuth clients	`oauthClients:create`, `oauthClients:read`, `oauthClients:update`, `oauthClients:delete`
LLM proxy and usage	`llm:invoke`, `llm:usage.read`, `llm:logs.read`, `llm:logs.write`
Secrets	`secrets:read`, `secrets:write`, `secrets:delete`, `secrets:grant`, `secrets:proxy`

Current tokens also accept compatibility aliases used by older clients, such as profile, create_rooms, connect_room, managed_agents, llm_proxy, developer, and admin, when they map to the current scope names.

Effective Permissions

Effective permissions are the checks MeshAgent evaluates after combining direct resource roles with inherited project roles. You do not assign these directly; you grant the roles that satisfy them.

Permission	Applies to	Satisfied by	What it controls
`room.can_use`	Rooms	`viewer`, `operator`, `developer`, or `admin` on the room	Whether the subject can use the room.
`room.accessible`	Rooms	`list` or `room.can_use`	Whether the room is visible or otherwise accessible to the subject.
`room.can_inventory`	Rooms	Project `room_inventory`	Whether the subject can inspect room inventory.
`room.can_debug`	Rooms	Room `developer`, room `admin`, or project `room_manager`	Whether the subject can use room debugging surfaces.
`room.can_manage`	Rooms	Room `admin` or project `room_manager`	Whether the subject can manage the room.
`agent.can_use`	Managed agents	`viewer`, `operator`, `developer`, or `admin` on the agent	Whether the subject can use the agent.
`agent.accessible`	Managed agents	`list` or `agent.can_use`	Whether the agent is visible or otherwise accessible to the subject.
`agent.can_inventory`	Managed agents	Project `agent_inventory`	Whether the subject can inspect agent inventory.
`agent.can_manage`	Managed agents	Agent `admin` or project `agent_manager`	Whether the subject can manage the agent.
`repository.can_use`	Repositories	`viewer`, `operator`, `developer`, or `admin` on the repository	Whether the subject can use the repository.
`repository.accessible`	Repositories	`list` or `repository.can_use`	Whether the repository is visible or otherwise accessible to the subject.
`repository.can_inventory`	Repositories	Project `repository_inventory`	Whether the subject can inspect repository inventory.
`repository.can_manage`	Repositories	Repository `admin` or project `repository_manager`	Whether the subject can manage the repository.
`feed.can_read`	Feeds	`reader`, `subscriber`, `publisher`, or `manager` on the feed	Whether the subject can read feed items.
`feed.accessible`	Feeds	`list` or `feed.can_read`	Whether the feed is visible or otherwise accessible to the subject.
`feed.can_subscribe`	Feeds	Feed `subscriber` or `manager`	Whether the subject can subscribe to the feed.
`feed.can_publish`	Feeds	Feed `publisher` or `manager`	Whether the subject can publish to the feed.
`feed.can_inventory`	Feeds	Project `feed_inventory`	Whether the subject can inspect feed inventory.
`feed.can_manage`	Feeds	Feed `manager` or project `feed_manager`	Whether the subject can manage the feed.

Room API Scope Permissions

Room API scopes are embedded in participant tokens. They are not project roles. They control what a connected participant can call inside a room. If a grant object is absent, that API surface is denied. When a grant object exists, None in an allowlist generally means unrestricted access within that grant, and a boolean set to false disables that operation.

`livekit`

Permission	Controls	What it does
`livekit.breakout_rooms`	Breakout room membership	`None` allows any breakout room. A list allows only the named breakout rooms.

`queues`

Permission	Controls	What it does
`queues.send`	Queue publishing	`None` allows sending to any queue. A list allows only the named queues.
`queues.receive`	Queue consumption	`None` allows receiving from any queue. A list allows only the named queues.
`queues.list`	Queue listing	Allows listing queues when `true`.

`messaging`

Permission	Controls	What it does
`messaging.broadcast`	Broadcast messages	Allows broadcasting messages to room participants.
`messaging.list`	Message listing	Allows listing messages.
`messaging.send`	Direct message sending	Allows sending messages.

`dataset`

Permission	Controls	What it does
`dataset.list_tables`	Dataset table listing	Allows listing dataset tables.
`dataset.tables[].name`	Table selection	Names the table covered by the grant.
`dataset.tables[].namespace`	Table namespace selection	Restricts the table grant to a namespace. `None` matches any namespace.
`dataset.tables[].read`	Table reads	Allows reading matching tables.
`dataset.tables[].write`	Table writes	Allows writing matching tables.
`dataset.tables[].alter`	Table schema changes	Allows altering matching tables.

If dataset.tables is None, the participant may read, write, and alter every dataset table allowed by the grant.

`sqlite`

Permission	Controls	What it does
`sqlite.create_database`	Database creation	Allows creating SQLite databases.
`sqlite.list_databases`	Database listing	Allows listing SQLite databases.
`sqlite.databases[].name`	Database selection	Names the database covered by the grant.
`sqlite.databases[].namespace`	Database namespace selection	Restricts the database grant to a namespace. `None` matches any namespace.
`sqlite.databases[].create_table`	Table creation	Allows creating tables in the matching database.
`sqlite.databases[].drop`	Database deletion	Allows dropping the matching database.
`sqlite.databases[].inspect`	Database inspection	Allows inspecting the matching database.
`sqlite.databases[].list_tables`	Table listing	Allows listing tables in the matching database.
`sqlite.databases[].execute`	SQL execution	Allows executing SQL against the matching database.
`sqlite.databases[].tables[].database`	Table database selection	Names the database for a table-specific grant.
`sqlite.databases[].tables[].table`	Table selection	Names the table covered by the table-specific grant.
`sqlite.databases[].tables[].namespace`	Table namespace selection	Restricts the table grant to a namespace. `None` matches any namespace.
`sqlite.databases[].tables[].read`	Table reads	Allows reading matching tables.
`sqlite.databases[].tables[].write`	Table writes	Allows writing matching tables.
`sqlite.databases[].tables[].alter`	Table schema changes	Allows altering matching tables.

If sqlite.databases is None, the participant may use all SQLite databases allowed by the grant. If a matching database grant has tables: None, table read, write, and alter access applies to all tables in that database.

`memory`

Permission	Controls	What it does
`memory.list`	Memory listing	Allows listing memories.
`memory.memories[].name`	Memory selection	Names the memory covered by the grant.
`memory.memories[].namespace`	Memory namespace selection	Restricts the memory grant to a namespace. `None` matches any namespace.
`memory.memories[].permissions.create`	Memory creation	Allows creating the matching memory.
`memory.memories[].permissions.drop`	Memory deletion	Allows dropping the matching memory.
`memory.memories[].permissions.inspect`	Memory inspection	Allows inspecting the matching memory.
`memory.memories[].permissions.query`	Memory querying	Allows querying the matching memory.
`memory.memories[].permissions.upsert`	Memory upserts	Allows upserting into the matching memory.
`memory.memories[].permissions.ingest`	Memory ingestion	Allows ingesting content into the matching memory.
`memory.memories[].permissions.recall`	Memory recall	Allows recall operations on the matching memory.
`memory.memories[].permissions.optimize`	Memory optimization	Allows optimizing the matching memory.

If memory.memories is None, the participant may use all memories allowed by the grant.

`sync`

Permission	Controls	What it does
`sync.paths[].path`	Sync path selection	Allows matching paths. A path may end with `*` to match a prefix.
`sync.paths[].read_only`	Sync write access	When `true`, matching paths can be read but not written.

If sync.paths is None, the participant may read and write all sync paths allowed by the grant.

`storage`

Permission	Controls	What it does
`storage.paths[].path`	Storage path selection	Allows paths that start with the configured prefix.
`storage.paths[].read_only`	Storage write access	When `true`, matching paths can be read but not written.

If storage.paths is None, the participant may read and write all storage paths allowed by the grant.

`containers`

Permission	Controls	What it does
`containers.use_containers`	Container API use	Enables container operations when `true`.
`containers.logs`	Container logs	Allows reading container logs when `true`.
`containers.pull`	Image pull allowlist	`None` allows pulling any image tag. A list allows exact tags or prefixes ending in `*`.
`containers.run`	Image run allowlist	`None` allows running any image tag. A list allows exact tags or prefixes ending in `*`.
`containers.registry.list`	Registry repository listing	`None` allows listing repositories implied by pull, run, or write access. A list allows exact repositories or prefixes ending in `*`.
`containers.registry.pull`	Registry pull access	`None` allows pulling any repository. A list allows exact repositories or prefixes ending in `*`.
`containers.registry.run`	Registry run access	`None` allows running any repository. A list allows exact repositories or prefixes ending in `*`.
`containers.registry.write`	Registry write access	`None` allows writing any repository. A list allows exact repositories or prefixes ending in `*`.

If containers.registry is absent, registry list, pull, run, and write checks allow any repository covered by the container grant.

`developer`

Permission	Controls	What it does
`developer.logs`	Developer logs	Allows developer log forwarding when `true`.

`agents`

Permission	Controls	What it does
`agents.register_agent`	Agent registration	Allows registering agents.
`agents.register_public_toolkit`	Public toolkit registration	Allows registering public toolkits.
`agents.register_private_toolkit`	Private toolkit registration	Allows registering private toolkits.
`agents.call`	Agent calls	Allows invoking the Agents API.
`agents.use_agents`	Agent use	Allows using agents.
`agents.use_tools`	Tool use	Allows using tools.
`agents.allowed_toolkits`	Toolkit allowlist	`None` allows all toolkits. A list restricts access to the named toolkits.

`llm`

Permission	Controls	What it does
`llm.models`	Model allowlist	`None` allows any provider/model. A list allows exact `provider/model` entries or prefixes ending in `*`.

`admin`

Permission	Controls	What it does
`admin.config`	Room admin configuration	Allows using the room admin configuration surface when `true`.

`secrets`

Permission	Controls	What it does
`secrets`	Secret grant presence	Enables room API routes that require the secrets grant. The grant has no nested fields.

`tunnels`

Permission	Controls	What it does
`tunnels.ports`	Tunnel port allowlist	`None` or an empty list allows any port. A non-empty list allows only the listed ports. If `tunnels` is absent, tunnels are denied.

`services`

Permission	Controls	What it does
`services.list`	Service listing	Allows listing services in the room when `true`.

Built-in Room API Scope Presets

Preset	Grants
`ApiScope.user_default()`	Livekit, queues, messaging, dataset, SQLite, memory, sync, storage, containers, developer logs, agents, and service listing. It excludes LLM, admin config, secrets, and tunnels.
`ApiScope.agent_default()`	Same core access as `user_default()` plus LLM. It excludes admin config, secrets, and tunnels unless called as `ApiScope.agent_default(tunnels=True)`.
`ApiScope.full()`	Livekit, queues, messaging, dataset, SQLite, memory, sync, storage, containers, developer logs, agents, LLM, admin config, tunnels, and service listing.

Managing IAM

Use MeshAgent Studio for day-to-day member management. Use the CLI or SDKs when provisioning access from automation.

meshagent iam policy --project-id <project-id> --resource-type room --resource-id <room-id>
meshagent iam grant --project-id <project-id> --resource-type room --resource-id <room-id> \
  --subject-type user --subject-id <user-id> --role viewer
meshagent iam revoke --project-id <project-id> --resource-type room --resource-id <room-id> \
  --subject-type user --subject-id <user-id> --role viewer

Introduction

Rooms

Agents & Tools

Deploy & Manage

Projects

Product Interfaces

Developer Reference

IAM Roles and Permissions

Principals

Resources

Project Roles

User profile permissions

Room, Agent, and Repository Roles

Group Roles

Feed Roles

Secret Roles

Service Account Roles

OAuth Scopes

Effective Permissions

Room API Scope Permissions

`livekit`

`queues`

`messaging`

`dataset`

`sqlite`

`memory`

`sync`

`storage`

`containers`

`developer`

`agents`

`llm`

`admin`

`secrets`

`tunnels`

`services`

Built-in Room API Scope Presets

Managing IAM

​Principals

​Resources

​Project Roles

​User profile permissions

​Room, Agent, and Repository Roles

​Group Roles

​Feed Roles

​Secret Roles

​Service Account Roles

​OAuth Scopes

​Effective Permissions

​Room API Scope Permissions

​livekit

​queues

​messaging

​dataset

​sqlite

​memory

​sync

​storage

​containers

​developer

​agents

​llm

​admin

​secrets

​tunnels

​services

​Built-in Room API Scope Presets

​Managing IAM

​Related Guides

Principals

Resources

Project Roles

User profile permissions

Room, Agent, and Repository Roles

Group Roles

Feed Roles

Secret Roles

Service Account Roles

OAuth Scopes

Effective Permissions

Room API Scope Permissions

`livekit`

`queues`

`messaging`

`dataset`

`sqlite`

`memory`

`sync`

`storage`

`containers`

`developer`

`agents`

`llm`

`admin`

`secrets`

`tunnels`

`services`

Built-in Room API Scope Presets

Managing IAM

Related Guides