Best Practices
Keep permissions simple. Assign roles based on who needs to build, who needs to view, who needs to chat, and who needs to govern.Organization Level
- Owners — have full control including billing and can delete the organization. Assign to 1-2 people maximum (CEO, CTO, or Head of Operations). Owners have all Admin permissions plus billing control.
- Admins — set up and manage teams, projects, and authentication. Usually your workspace or IT leads.
- Members — can only access projects they’re assigned to. Cannot create projects at the organization level. Asset creation within projects is controlled by project-level permissions. Best for users who need access to specific projects but shouldn’t manage organization-wide settings.
- Viewers — view-only access to audit logs, usage data, and compliance reports. Use this for stakeholders who need visibility without operational access.
Project Level
| Role | When to use it |
|---|---|
| Admins | Own the project setup and governance. They control permissions and authentication accounts. |
| Editors | Build, edit, and run all assets in the project. Treat them as your core contributors. |
| Members | Can build their own assets but don’t automatically see or edit others’. Best for independent work within shared projects. |
| Chat | Access Relevance Chat only, cannot access the web app. Requires asset-level permissions to run agents. |
| Viewers | Can’t build or edit. Add them only to the specific assets they need to see. |
Asset Level
- Project admins and editors automatically have full control.
- Members can run assets but can’t modify them unless granted edit rights.
- Viewers can only see results or outputs — they can’t run or trigger anything.
Organization level controls
New organization members will be given viewer permissions by default. If invited, their role will be selected during invite.Roles
| Role | Capabilities |
|---|---|
| Owner | Full control of organization, billing, security, users and all projects |
| Admin | Manage users, projects, organization-level API keys and OAuths |
| Member | Access only assigned projects. Cannot create projects at organization level. Asset creation within projects is controlled by project-level permissions. |
| Viewer | View-only access to agent and tool audit logs, usage data and compliance reports |
Permissions
| Permission | Owner | Admin | Member | Viewer |
|---|---|---|---|---|
| Manage billing | ✅ | ❌ | ❌ | ❌ |
| Manage organization settings (name, logo, domain etc.) | ✅ | ✅ | ❌ | ❌ |
| Manage organization users | ✅ | ✅ | ❌ | ❌ |
| Manage API keys & OAuths (Org-level connections) | ✅ | ✅ | ❌ | ❌ |
| View global audit logs | ✅ | ✅ | ❌ | ❌ |
| View all projects and agents | ✅ | ✅ | ❌ | ❌ |
| Delete any asset | ✅ | ✅ | ❌ | ❌ |
| Edit project roles | ✅ | ✅ | ❌ | ❌ |
| View credit information | ✅ | ✅ | ❌ | ❌ |
| Create projects | ✅ | ✅ | ❌ | ❌ |
| View organization members / admins | ✅ | ✅ | ✅ | ✅ |
Project level controls
Project admins will be able to set a users role upon invite. Organization admins can also set this for any project.Roles
| Role | Capabilities |
|---|---|
| Admin | Manage users, agents, tools, knowledge and project-level integrations. Can create assets |
| Editor | Can edit and create assets, does not manage users |
| Member | Use shared assets, provide inputs and view outputs. Can create assets, private by default. |
| Chat | Access Relevance Chat only - cannot access the web app. Requires asset-level permissions to run agents. |
| Viewer | View agents, tools, and knowledge outputs only, cannot run or edit anything |
Editor is a project-level role only and does not exist at organization or asset levels. Project Editors automatically have Admin permissions on all assets within the project.
Permissions
| Permission | Admin | Editor | Member | Viewer | Chat |
|---|---|---|---|---|---|
| Delete project | ✅ | ❌ | ❌ | ❌ | ❌ |
| Assign project roles to users | ✅ | ❌ | ❌ | ❌ | ❌ |
| Manage project-level API keys & OAuths | ✅ | ❌ | ❌ | ❌ | ❌ |
| Add personal OAuth accounts (dynamic auth) | ✅ | ✅ | ✅ | ✅ | ✅ |
| Delete agents | ✅ | ✅ | ❌ | ❌ | ❌ |
| View all assets by default | ✅ | ✅ | ❌ | ❌ | ❌ |
| Edit/run assets they did not create | ✅ | ✅ | ❌ | ❌ | ❌ |
| View project activity logs | ✅ | ✅ | ❌ | ❌ | ❌ |
| Manage personal Relevance API key | ✅ | ✅ | ✅ | ❌ | ❌ |
| Create assets | ✅ | ✅ | ✅ | ❌ | ❌ |
| View Project | ✅ | ✅ | ✅ | ✅ | ❌ |
| Access Web App | ✅ | ✅ | ✅ | ✅ | ❌ |
| Run a chat (LLM) | ✅ | ✅ | ✅ | ✅ | ✅ |
Project Viewer access grants read-only visibility to full asset configurations — including prompts, tools, and steps. There is no field-level redaction. If a Viewer cannot see an agent’s internals, it’s because they lack asset-level access entirely, not because their read access is limited to metadata.
“Manage project-level API keys & OAuths” refers to shared, project-wide accounts only. All team members can add their own personal OAuth accounts when dynamic authentication is enabled on a shared agent — this is not restricted to admins.
Chat Role Details
The Chat role is designed for users who only need to interact with AI agents through Relevance Chat without accessing the main web application. Key characteristics:Controlled agent visibility
Controlled agent visibility
Chat role users can only see and run agents they have Member or higher permissions on. They won’t be able to see any other agents in Chat. This allows you to control exactly which agents each Chat user can access by assigning asset-level permissions.
Chat-only access
Chat-only access
Users with this role are automatically redirected to Chat and cannot access the web app.
No asset creation
No asset creation
Cannot create new agents, tools, or knowledge bases.
LLM conversations
LLM conversations
Can have conversations with LLMs and in-built Chat Agents directly without agents.
More powerful than Viewer
More powerful than Viewer
Can trigger Chat and interact with agents (with proper asset permissions).
Less powerful than Member
Less powerful than Member
Cannot create assets or access the web app.
Asset level controls
An asset is an Agent, Tool, Knowledge or Workforce. Upon asset creation, the creator becomes the admin. An asset can have multiple admins (project admin is by default).Roles
| Role | Capabilities |
|---|---|
| Admin | Manage asset configuration, tools, knowledge and assign asset-level users |
| Member | Use asset only, provide inputs and view outputs |
| Viewer | View asset configuration and outputs only, cannot run or edit anything |
Permissions
| Permission | Admin | Member | Viewer |
|---|---|---|---|
| Edit asset | ✅ | ❌ | ❌ |
| Delete asset | ✅ | ❌ | ❌ |
| Assign roles on asset | ✅ | ❌ | ❌ |
| Assign auth per tool | ✅ | ❌ | ❌ |
| Enable cloning/sharing of asset | ✅ | ❌ | ❌ |
| Create tasks on asset | ✅ | ✅ | ❌ |
| View asset configuration | ✅ | ✅ | ✅ |
| View asset outputs | ✅ | ✅ | ✅ |
| View asset audit logs | ✅ | ✅ | ✅ |
Asset Viewer access grants read-only visibility to full asset configurations — including prompts, tools, and steps. There is no field-level redaction. If a Viewer cannot see an agent’s internals, it’s because they lack asset-level access entirely, not because their read access is limited to metadata.
Workforce Permissions
Workforces are treated as first-class assets in the RBAC system. However, running a workforce requires permissions at two levels:- Workforce permission - The user must have at least Member (run) access to the workforce itself
- Agent permissions - The user must have at least Member (run) access to each agent used within the workforce
- Share the workforce with the user at the desired permission level
- Share each agent in the workforce at a matching (or higher) permission level
Example scenarios
| Goal | Workforce Role | Agent Roles |
|---|---|---|
| User can run workforce | Member | Member on all agents |
| User can edit workforce | Admin | Admin on all agents |
| User can view but not run | Viewer | Viewer on all agents |
Note: If a user has run access to a workforce but lacks permissions on one or more agents, they will see a “Cannot run agent” warning in the workforce builder and will be unable to execute the workflow.
Transitioning to RBAC
If your organization is being migrated from legacy permissions to RBAC, this section covers what changes, what stays the same, and what actions you need to take.Before RBAC (legacy permissions)
The legacy permission system had three roles — Admin, Editor, and Viewer — applied at the project and organization level only:Admin
Full read and write access to all assets and settings.
Editor
Read and write access to all datasets, knowledge sets, and agents. Could run agents and tools.
Viewer
Read access to all datasets, knowledge sets, and agents. Could run agents.
During the migration
The Relevance AI team handles the technical migration to RBAC. You do not need to manually migrate roles, but you should review and adjust assignments after migration is complete. How legacy roles map to RBAC roles by default:| Legacy role | Default RBAC role (project level) |
|---|---|
| Admin | Admin |
| Editor | Editor |
| Viewer | Viewer |
- Chat — for users who only need to use agents through Relevance Chat
- Viewer — for users who genuinely only need read access to asset configurations and outputs
- Member — for users who need to run agents
After RBAC is enabled
Once RBAC is active for your organization:Asset-level permissions are enforced
Asset-level permissions are enforced
Access to individual agents, tools, and knowledge bases is controlled separately from project-level roles.
Editors and Admins keep full access
Editors and Admins keep full access
Project Admin and Editor roles cascade to asset Admin on every asset in the project automatically.
Everyone else needs explicit grants
Everyone else needs explicit grants
Members, Viewers, and Chat users receive a 403 error on any asset they have not been granted access to.
Credentials can be scoped per tool
Credentials can be scoped per tool
Instead of one set of project-wide credentials, asset admins can assign specific authentication accounts per tool.
Permissions live in the Share modal
Permissions live in the Share modal
Action items for admins
After RBAC is enabled, complete these steps to restore appropriate access for your team:Review user roles immediately
Check that the default role mappings match your intended access levels, particularly for legacy Viewer accounts.
Assign asset-level permissions
Use the Share modal on each agent, tool, and knowledge base that non-Admin/Editor users need to access.
Use RBAC Groups for bulk assignment
If many users need the same access, create a group and assign asset permissions to the group rather than to individual users.
Audit chat-only users
Confirm that users who only need Relevance Chat access are assigned the Chat project role, not Viewer.
Permission inheritance and cascading
Project roles fall into two groups: those that cascade Admin access to every asset automatically, and those that start with no asset access until it is explicitly granted.Cascades to asset Admin
Admin and Editor automatically receive Admin access on every asset in the project — no per-asset setup required.
Starts with no access
Member, Viewer, and Chat receive nothing by default. Each asset must be shared with them explicitly, or they get a 403 error.
To grant access at scale, assign asset permissions to an RBAC Group rather than to each user individually.
Technical implementation notes
The following is relevant primarily for API users and developers integrating directly with the authorization system.- Member/Operator
- OpenFGA
- Embeddable agents
The “Member” role label in the UI maps to the
operator role in the authorization system. When querying permissions via the API, use operator rather than member.Frequently asked questions (FAQs)
Can I access role-based access controls without upgrading to Enterprise?
Can I access role-based access controls without upgrading to Enterprise?
No. This feature is available for Enterprise subscriptions only.
I'm on an Enterprise subscription but do not have access to this feature yet. How do I get access?
I'm on an Enterprise subscription but do not have access to this feature yet. How do I get access?
This feature is gradually being rolled out to Enterprise customers. Please reach out to your sales representative to express your interest in receiving this feature.
How do I limit someone to only access Chat?
How do I limit someone to only access Chat?
To limit a user to only access Relevance Chat, assign them the Chat role at the project level. Users with the Chat role are automatically redirected to Chat and cannot access the main web application. They can still interact with agents and have LLM conversations, but will need appropriate asset-level permissions (Member or higher) on specific agents to run them in Chat.
Is there a role that allows a user to approve escalations or interact with agent tasks, but not edit the agent?
Is there a role that allows a user to approve escalations or interact with agent tasks, but not edit the agent?
Yes, assigning a user the Asset Member role for a specific agent allows them to create tasks on the agent, approve/reject escalations, and view outputs, but not edit or delete the agent’s configuration.