> ## Documentation Index > Fetch the complete documentation index at: https://docs.meshagent.com/llms.txt > Use this file to discover all available pages before exploring further. # IAM Roles and Permissions > Every MeshAgent IAM principal, resource, role, and room API scope permission. 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. ```bash theme={null} # 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](../rest_api/overview#user-profiles) for SDK examples, or [Editing user profiles in Accounts](../interfaces/accounts#edit-user-profiles) 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. ```bash theme={null} meshagent iam policy --project-id --resource-type room --resource-id meshagent iam grant --project-id --resource-type room --resource-id \ --subject-type user --subject-id --role viewer meshagent iam revoke --project-id --resource-type room --resource-id \ --subject-type user --subject-id --role viewer ``` ## Related Guides * [Project Roles and Access](./project_roles) * [API Keys](./api_keys) * [Participant Tokens](../rest_api/participant_tokens) * [API Scopes](../rest_api/api_scopes) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.