Roles and permissions
Role-based access control system with hierarchical permissions at organization and project levels
MagOneAI uses a tiered role-based access control (RBAC) system to manage user permissions. Roles are assigned at both the organization and project level, allowing you to grant exactly the access each user needs while maintaining strict isolation between organizations.
Role hierarchy
The RBAC system follows a hierarchical structure with three distinct scopes:
- Platform level — the Superadmin flag, a platform-wide override.
- Organization level — Owner, Admin, and Member, assigned per organization.
- Project level — Admin, Builder, Operator, and Viewer, assigned per project.
A user can hold different roles in different organizations and projects. Within each scope, higher roles inherit every permission of the roles beneath them.
How you get a project role depends on the project type:
- Default project (every organization has one) — no explicit membership needed. Your org role maps to a project role automatically: Owner → Admin, Admin → Builder, Member → Operator. (The lowest level in a default project is Operator — there is no Viewer there.)
- Team project — requires explicit membership. Being in the organization is not enough; you must be added to the project with a specific role (Admin / Builder / Operator / Viewer).
Organization roles
Assigned per organization. Hierarchy: Owner > Admin > Member.
Scope: Single organization
Everything an Admin can do, plus the highest-trust actions for the org.
Capabilities:
- Delete the organization
- Manage billing and SSO configuration
- Manage OAuth / tool credentials for the organization
- Promote other members to Owner
- Access every project in the organization
Restriction: Only an Owner can promote someone to Owner.
Who needs this role: Department heads or administrators accountable for a business unit's AI resources. Keep this to a small number of people.
Scope: Single organization
Everything a Member can do, plus organization management short of ownership.
Capabilities:
- Invite and remove members
- Change member roles (but cannot grant Owner)
- Create and delete projects
- Manage organization settings
Restriction: An Admin cannot remove or demote an Owner.
Who needs this role: Team leads who run day-to-day org administration.
Scope: Organization, plus the default project
Capabilities:
- Access organization resources
- Work in the default project as an Operator (run workflows, chat, upload files)
- Join team projects when explicitly added, at the role they're given
Limitations:
- Cannot create projects or manage members
- Cannot manage organization settings or providers
Who needs this role: Most users in an organization.
Project roles
Assigned per project (or mapped automatically in the default project). Hierarchy: Admin > Builder > Operator > Viewer.
Everything a Builder can do, plus:
- Add, remove, and change project members' roles
- Grant or revoke which LLM configurations the project can use
- Create and revoke project API keys
- Update project settings
Who needs this role: Project leads. Typically 1–3 people per project.
Everything an Operator can do, plus:
- Create / update / delete agents
- Create / update / delete / duplicate / import / export use cases
- Create and delete knowledge bases and documents
- Create / update / delete MCP connections and schedules (pause/resume)
- Create / update / delete test cases and manage baselines
- Write secrets, initiate OAuth connections, generate use-case documentation
- Delete executions and files
Who needs this role: Developers and builders working on agents and workflows.
Everything a Viewer can do, plus:
- Run workflows
- Create conversations and send messages (which trigger agent runs)
- Upload files
- Manually trigger a schedule
- Run test cases and test suites
Who needs this role: Business users who execute workflows and chat with agents but don't build them. This is the level a default-project Member receives.
Can see everything in the project, change nothing:
- View agents, use cases (incl. workflow config and variables), executions and activity logs
- View chat conversations and messages
- List and download files; search knowledge bases
- View schedules, test cases and reports, and project/use-case analytics
- List API keys and view their stats; read secrets
Who needs this role: Reviewers and auditors who need visibility without the ability to run or change anything. (Available in team projects only.)
Superadmin (platform)
The Superadmin flag is a platform-wide override, not an organization or project role. It is set only via the bootstrap script or database — it cannot be granted through the UI by other users.
Capabilities:
- Bypasses all permission checks across every organization and project
- Manages platform settings (email configuration, global MCP servers)
- Views platform-wide stats and LLM usage
- Publishes, edits, and removes Blueprint listings in the shared catalog
- Is effectively treated as Owner in every organization and Admin in every project
Grabbing a blueprint is not a superadmin action. Any user with write access to a project can copy a published blueprint into it. Only publishing to the catalog is restricted.
Superadmin is full, platform-wide access — a superadmin can reach any organization's and project's data. Grant it to as few people as possible (typically 1–2), and do day-to-day org/project work with normal roles. Isolation between regular members still holds: a non-superadmin in one organization has no visibility into another.
Permissions matrix
Organization scope
| Action | Owner | Admin | Member |
|---|---|---|---|
| Access organization resources | ✓ | ✓ | ✓ |
| Create / delete projects | ✓ | ✓ | - |
| Invite / remove members | ✓ | ✓ | - |
| Change member roles | ✓ | ✓ (not Owner) | - |
| Manage organization settings | ✓ | ✓ | - |
| Manage billing / SSO | ✓ | - | - |
| Manage OAuth credentials | ✓ | - | - |
| Promote a member to Owner | ✓ | - | - |
| Delete the organization | ✓ | - | - |
Project scope
| Action | Viewer | Operator | Builder | Admin |
|---|---|---|---|---|
| View resources | ✓ | ✓ | ✓ | ✓ |
| Run workflows / chat | - | ✓ | ✓ | ✓ |
| Upload files | - | ✓ | ✓ | ✓ |
| Trigger a schedule | - | ✓ | ✓ | ✓ |
| Run test cases | - | ✓ | ✓ | ✓ |
| Create / edit / delete agents | - | - | ✓ | ✓ |
| Create / edit / delete use cases | - | - | ✓ | ✓ |
| Manage knowledge bases | - | - | ✓ | ✓ |
| Manage MCP connections & schedules | - | - | ✓ | ✓ |
| Write secrets | - | - | ✓ | ✓ |
| Manage project members | - | - | - | ✓ |
| Manage LLM access | - | - | - | ✓ |
| Manage project API keys | - | - | - | ✓ |
| Update project settings | - | - | - | ✓ |
Organization isolation
Organization isolation is a fundamental security principle in MagOneAI. Each organization functions as a complete data boundary with no cross-organization access.
Isolation guarantees
- Data isolation — Organizations cannot see or access data from other organizations. This includes agents, workflows, execution logs, knowledge bases, and all metadata.
- User isolation — Users belong to specific organizations. A regular user in Organization A has no visibility into Organization B, even if the same person is a member of both organizations.
- Provider isolation — Model provider configurations are scoped to organizations. Credentials configured in one organization are not accessible to others.
- Audit isolation — Audit logs are scoped to organizations. Org Owners and Admins see logs for their organization only.
Isolation applies between regular members. The Superadmin flag is a deliberate exception: it bypasses these checks and can reach data in any organization. Treat Superadmin as a privileged break-glass account — grant it sparingly and audit its use.
API key management
API keys provide programmatic access to trigger a project's workflows. Keys are scoped to a project — a key can start that project's published workflows (and hold chat sessions for chat-enabled workflows). They are credentials for the external API, not a way to grant resource permissions. See Triggers & execution for how to sign and send API requests.
Creating API keys
Navigate to project settings
In Studio, go to the project where you need API access and open Settings.
Generate a new API key
Click "Create API Key" and provide a descriptive name (e.g., "Production deployment - ETL workflow").
Store the key and secret securely
You receive a key identifier and a signing secret. Copy the secret and store it in your secrets management system (like HashiCorp Vault) — it is only shown once. The secret is used to sign API requests (HMAC); the key identifier appears in the request URL.
API keys do not carry per-key permission toggles and do not inherit a user's role. Any valid key for a project can trigger that project's published workflows via the API. Control exposure by creating one key per integration and revoking keys you no longer use.
Key rotation
To rotate an API key without downtime:
- Create a new API key
- Update your application to use the new key
- Verify the new key is working in production
- Revoke the old key
The old key remains active until explicitly revoked, allowing for zero-downtime rotation.
Key revocation
Revoke a key immediately if:
- The key is compromised or accidentally exposed
- The user who created the key leaves the organization
- The key is no longer needed
Revocation is instant — all requests using the revoked key will fail immediately.
Audit trail
All API key usage is logged in the project audit trail:
- Key creation with creator and timestamp
- Every API request with key ID, endpoint, and timestamp
- Key revocation with user and reason
Treat the signing secret like a password — anyone holding it can trigger the project's workflows. Create separate keys for different applications, store secrets in a vault, and revoke keys as soon as they're no longer needed.
Role assignment workflows
Adding a new organization member
Invite the user
As an Owner or Admin, navigate to Organization Settings → Members and click "Invite Member".
Assign organization role
Choose the user's organization role: Member (standard), Admin (manages members and projects), or Owner (full org control).
Assign to team projects
The user automatically gets default-project access mapped from their org role. For team projects, add them explicitly and pick a project role (Admin / Builder / Operator / Viewer).
User accepts invitation
The user receives an email invitation and creates their account or links their SSO identity.
Promoting a user to Project Admin
Review current access
Ensure the user is already a project member (Builder or below) and has demonstrated the need for elevated permissions.
Update role
As an Org Owner/Admin or an existing Project Admin, go to Project Settings → Members and change the user's role to Admin.
Communicate responsibilities
Inform the user of their new responsibilities, including managing project members, LLM access, and settings.
Offboarding a user
Revoke organization access
As an Org Owner, remove the user from the organization in Organization Settings → Members.
Revoke API keys
Revoke any API keys created by the user in all projects they had access to.
Revoke OAuth tokens
If the user had OAuth integrations, revoke their tokens in the Admin Portal or organization settings.
Review audit logs
Check audit logs for any unusual activity during the user's final days of access.
Best practices
Apply least privilege
Assign the minimum role needed for each user's responsibilities. Most users should be Operators (run and chat) or Viewers (read-only); reserve Builder and Admin for those who need them.
Regular access reviews
Quarterly review of all user roles and permissions. Remove access for inactive users.
Separate production and development
Use different projects for development and production with separate team assignments.
Limit Owners and Superadmins
Keep Org Owners to 2–3 per organization, and platform Superadmins to 1–2. Too many high-trust accounts reduces accountability.
Document role decisions
Maintain documentation explaining why each user has their assigned role.
Automate offboarding
Integrate with your HR system to automatically revoke access when employees leave.
Role-based access control is most effective when combined with other security measures. Use RBAC alongside HashiCorp Vault for secrets management, comprehensive audit logging, and network-level security controls for defense-in-depth.