Role-Based Access Control (RBAC)
Agenta uses role-based access control (RBAC) to manage what members can do inside an organization and its projects.
Roles apply in every edition and on every plan. The plan decides only which roles you can give:
| Edition or plan | Roles you can give |
|---|---|
| Open source, Cloud Hobby, Cloud Pro | Admin, Member |
| Cloud Business, Enterprise | Admin, Member, Developer, Editor, Annotator, Viewer |
Nobody can give the Owner role. Ownership moves only when the owner transfers the organization. A member who has a role that the plan does not offer, such as a Viewer in the open source edition, keeps that role and its permissions.
Roles
Agenta has seven built-in roles. Each role is a set of permissions.
| Role | What it is for |
|---|---|
| Owner | The one person who owns the organization. Has every permission, deletes projects, and transfers or deletes the organization |
| Admin | Manages members, roles, projects and billing, and reads traces and analytics |
| Member | Uses and builds agents, chats and automations. Cannot read traces, analytics or evaluations, and cannot manage members or billing |
| Developer | Deploys to environments, manages API keys, reads traces, and does everything an Editor can |
| Editor | Edits prompts, testsets, evaluators, workflows, and other project resources |
| Annotator | Runs evaluations, annotates traces, and reviews results |
| Viewer | Reads all project resources and changes nothing |
A new invite without a role gets Member on the open source edition, Hobby and Pro, and Viewer on Business and Enterprise.
Permissions
Under the hood, Agenta authorizes requests using granular permissions. These permissions cover actions and resources across the application, such as:
- Applications and variants
- Workflows, prompts, and configurations
- Evaluations, test sets, and evaluation queues
- Observability (traces/spans, annotations)
- Secrets and API keys
- Deployments and environments
- Workspace membership and roles
- Billing
Key permission boundaries
| Capability | Roles with this permission |
|---|---|
| View apps, prompts, workflows, testsets, agents and chats | Every role |
| See the credit balance | Every role |
| Read traces, analytics and evaluations | Owner, Admin, Developer, Editor, Annotator, Viewer (not Member) |
| Run evaluations and annotate traces | Owner, Admin, Developer, Editor, Annotator |
| Edit prompts, testsets, evaluators, workflows | Owner, Admin, Member, Developer, Editor |
| Run agents and send in chats | Owner, Admin, Member, Developer, Editor |
| Deploy to environments | Owner, Admin, Member, Developer |
| View and manage API keys | Owner, Admin, Member, Developer |
| Create and rename projects | Owner, Admin, Member |
| Invite members and assign roles | Owner, Admin |
Take ownership of an agent whose owner left the project (manage_agent_ownership) | Owner, Admin |
| Manage billing | Owner, Admin |
| Delete projects | Owner |
An API key acts with the role of the member who created it, and only in the project it belongs to.
What a Member cannot read
A Member runs agents and chats, and the traces of those runs are stored. A Member cannot read traces, spans, analytics, or evaluations, and cannot read an invocation or an annotation by its trace id. The API answers 403 to these reads. A Member sees the tokens and cost of each chat turn, because these are stored on the turn.
Owners and Admins can read every trace in the project, also the traces of a private chat. A private chat is private from other members, not from Owners and Admins.
Private agents and chats
Roles decide what a member can do with the items they can see. They do not open private items. A private agent or chat is visible only to its owner and, for a chat, the people the owner added. The Owner and Admin roles do not change this: an organization owner or a project admin cannot see another member's private agent or chat.
- Taking ownership. Admins and Owners have the
manage_agent_ownershippermission. It lets them take ownership of a shared agent whose owner left the project. It does not open private agents. - Sending in a shared chat. The Can send role in a chat works only for a member whose project role can run chats: Owner, Admin, Member, Developer or Editor. A Viewer or Annotator can only read a chat that is shared with them.
Managing Roles
Assign a Role
When you invite a member in Settings → Members, choose one of the roles that your plan offers.
Change a Role
- Open Settings → Members.
- In the member's row, choose a new role in the Role column.
Owners and Admins can change roles. The owner's role has no control, because ownership moves only by a transfer. Removing a member's role through the API gives them the plan's floor role: Member on the open source edition, Hobby and Pro, and Viewer on Business and Enterprise.
Best Practices
- On Hobby, Pro and the open source edition, give Member to people who use agents and chats, and Admin to people who debug traces or manage the team.
- On Business and Enterprise, give most contributors Editor access, which covers day-to-day prompt and evaluation work.
- Use Developer for team members who need to deploy to environments or manage API keys.
- Use Annotator for teammates focused on running evaluations and labeling traces.
- Use Viewer for stakeholders who need visibility but should not change anything.
- Reserve Admin for people who manage team membership, and Owner for a small number of people.
FAQ
Can I set different roles per project?
Project-level roles are currently not supported. This will be available in the future.
Can I create custom roles?
Custom roles are not currently supported. This will be available in the future.
What's the difference between Owner and Admin?
- Owner: One person. Has every permission, deletes projects, and transfers or deletes the organization.
- Admin: Can manage members, roles, projects and billing, but cannot delete projects, delete the organization or transfer it.
What's the difference between Member and Admin?
- Member: Can use and build agents, chats and automations, but cannot read traces, analytics or evaluations, or manage members or billing.
- Admin: Can do everything a Member can, and also read traces, analytics and evaluations, and manage members and billing.
What's the difference between Developer and Editor?
- Developer: Can deploy to environments, manage API keys, and do everything an Editor can.
- Editor: Can edit prompts, testsets, evaluators, and workflows, but cannot deploy or access API keys.