Skip to main content
Project roles control who can administer and operate a MeshAgent project. This is separate from room access. A person can have a project role and still need room access to work in a specific room, and someone can have room access without broad project administration rights.

​
Two layers of access

MeshAgent has two related but different permission layers:
  • Project roles decide who can administer and operate project-level resources.
  • Room grants decide who can access a specific room and which Room APIs they can use there.
That distinction matters:
  • project roles answer “what can this person manage across the project?”
  • room grants answer “what can this person or service do inside this room?”
For room-specific permissions, see REST API, Participant Tokens, and API Scopes.

​
Common project roles

MeshAgent has a default Member role, plus focused roles such as Room Creator and User Profile Editor, and broader roles such as Developer and Admin. The user who creates a project becomes its Owner. Owners inherit Admin access, including User Profile Editor, automatically.

​
Member

Member is the default project collaborator role. Use this when someone should be part of the project without extra project-wide privileges such as developer access, admin access, room-creation privileges, or LLM proxy/OAuth management access.

​
Room Creator

Room Creator is a limited project role for collaborators who create room-centered project resources. Use this when someone should be able to:
  • create new rooms
  • create mailboxes, routes, and scheduled tasks that attach work to rooms
  • organize work into separate rooms
But should not automatically manage the broader project surface such as billing, secrets, or member administration.

​
Agent Creator

Agent Creator is a focused project role for collaborators who need to create managed agent identities. Use this when someone should be able to create agents without giving them broader developer or admin access.

​
User Profile Editor

User Profile Editor (user_profile_editor) lets a member edit the first and last names, metadata, and annotations of users who belong to the project. Use this when someone needs to maintain user profiles without broad project administration access. Ordinary users can edit their own names and metadata. Editing annotations, including their own, requires User Profile Editor permission. The profile is shared across all projects the user belongs to, so edits are visible wherever that profile is used. The project controls permission to make the edit. See MeshAgent Accounts for the editing workflow and User profiles in the REST API for programmatic updates.

​
Developer

Developers are for people building and operating workloads without giving them full project administration. Use this role when someone needs to:
  • build and test in project rooms
  • inspect deployed services and runtime state
  • inspect operational resources such as mailboxes, routes, scheduled tasks, feed subscriptions, and LLM loggers
  • work in MeshAgent Studio and the CLI without managing the whole project
Developer does not include User Profile Editor. Grant user_profile_editor separately when a developer also needs to edit member profiles.

​
LLM Proxy User

LLM Proxy User is a focused project permission for collaborators who need project-level OpenAI or Anthropic routing without broader developer access. Use this when someone needs to:
  • call the project LLM proxy with OAuth access tokens
But should not automatically get the rest of the developer project surface.

​
Admin

Admins have full project-level control. Use this role when someone needs to:
  • manage members and role assignments
  • edit member names, metadata, and annotations through the inherited User Profile Editor permission
  • edit project settings
  • manage secrets, billing, domains, and other project-wide resources
  • deploy and manage services across the project

​
How project roles map to the API

In the admin API and SDKs, project membership is controlled with a roles list. The server normalizes that list to include member and expands inherited roles for admin and developer. Common role entries include:
  • admin
  • developer
  • room_creator
  • agent_creator
  • user_profile_editor
  • llm_proxy_user
Some older project member records and Studio settings still surface convenience booleans. They map to roles like this: If you are managing access programmatically, use the project user-management endpoints or SDK helpers that add and update project users.

​
How room grants and tokens fit in

Project roles and room access are related, but they are not the same thing.
  • Project role decides what someone can manage across the project.
  • Room grant decides what someone can do inside a specific room.
  • Participant token is the signed credential MeshAgent issues for an active room connection.
For room access, the important relationship is:
  1. A room grant stores the room-specific permissions.
  2. When MeshAgent creates a room connection for that person or service, it signs a participant token.
  3. That participant token carries the room-level API permissions used during the session.
For deployed services, the same idea applies through the service token configuration in the service spec: that token defines what the running service can do in the room. So if you are asking “what can this participant actually do in the room right now?”, the answer lives in the room grant or service token configuration, and in the participant token MeshAgent signed from it, not in the project role by itself.

​
Practical mental model

Use this rule of thumb:
  • If the question is about members, billing, domains, secrets, API keys, or project-wide services, think project role.
  • If the question is about joining a room, using Room APIs, or limiting what a participant can do inside a room, think room grant and participant token scope.
This is why a collaborator might need both:
  • a project role that lets them create rooms
  • a room grant that lets them access a specific room and use its APIs

​
Where to manage roles

  • MeshAgent Accounts: open Access Management for the project, then use the user’s menu to manage permissions or edit their profile.
  • MeshAgent Studio: use the Members tab for day-to-day role assignment.
  • REST API / SDKs: use the project user-management endpoints such as POST /accounts/projects/:id/users and PUT /accounts/projects/:id/users/:user_id, or the matching SDK helpers, when provisioning or syncing access from your own systems.