Skip to main content

​
Organization hierarchy

MagOneAI uses a clear, hierarchical structure to organize resources and manage access. Understanding this hierarchy is essential for using the platform effectively.

​
The three-tier structure

1

Organization (top level)

The top-level tenant. Each organization has completely isolated data, users, agents, workflows, and resources. Organizations enable multi-tenancy for enterprise deployments.
2

Project (middle level)

A container within an organization that groups related resources. Projects contain agents, use cases (workflows), tools, and knowledge bases.
3

Resources (bottom level)

The actual assets you work with: individual agents, use case workflows, tool connections, and knowledge bases. Resources are always scoped to a specific project.

​
Visual representation

Organization: "Acme Corp"
│
├── Project: "Customer Onboarding"
│   ├── Agents: KYB Analyst, Document Processor, Risk Evaluator
│   ├── Use Cases: KYB Verification Workflow, Document Review Workflow
│   ├── Tools: Google Search, Company Database API, OCR Service
│   └── Knowledge Bases: Regulatory Guidelines, Company Policies
│
├── Project: "Sales Automation"
│   ├── Agents: Lead Enrichment Agent, Proposal Generator
│   ├── Use Cases: Lead Scoring Workflow, RFP Response Workflow
│   ├── Tools: CRM API, LinkedIn Connector, Email Service
│   └── Knowledge Bases: Product Documentation, Case Studies
│
└── Project: "Internal Support"
    ├── Agents: IT Support Bot, HR Assistant
    ├── Use Cases: Ticket Triage Workflow, Employee Onboarding
    ├── Tools: Slack API, JIRA API, HR System Connector
    └── Knowledge Bases: IT Policies, HR Handbook
This structure provides logical separation while maintaining flexibility. Teams can work independently within their projects while sharing the organization’s infrastructure and security policies.

​
Multi-tenancy and isolation

MagOneAI’s architecture is designed for secure multi-tenancy, making it suitable for SaaS deployments, enterprise use cases, and managed service scenarios.

​
Each organization is fully isolated

Organizations are completely separate from one another:
Data isolation
  • Separate database schemas per organization
  • No shared tables or cross-org queries
  • Independent encryption keys
User isolation
  • Users belong to specific organizations
  • No cross-org user access
  • Independent authentication policies

​
Separate data, users, agents, workflows

Every resource in MagOneAI is scoped to an organization:
  • Agents — An agent created in Org A cannot be accessed or used by Org B
  • Workflows — Use cases are private to the organization that created them
  • Tools — Tool connections (and their OAuth tokens) are org-specific
  • Knowledge Bases — Documents uploaded to one org are not visible to others
This ensures complete data sovereignty and privacy.

​
No cross-org data access

Even platform administrators (SuperAdmins) cannot see the content of workflow executions or agent outputs without explicit audit log access. The platform is designed to prevent accidental or malicious cross-org data leakage.
Multi-tenancy is enforced at the database, application, and API levels. No organization can access another organization’s data, even through API misuse or misconfiguration.

​
Independent LLM provider configuration per org

Each organization can have its own LLM provider configuration:
  • Org A might use their own OpenAI API key
  • Org B might use Anthropic Claude
  • Org C might use a self-hosted model on Azure
This allows:
  • Bring Your Own Key (BYOK) — Customers can use their own LLM subscriptions
  • Cost allocation — Each organization’s LLM usage is billed to their own account
  • Model preference — Organizations choose models based on their needs and compliance requirements

​
Project structure

Projects provide a second level of organization within an organization (yes, that’s confusing — think of projects as “organizational sub-units”). A project is a logical container for resources that belong together:
  • Domain-based projects — “Customer Onboarding”, “Sales Automation”, “Compliance Monitoring”
  • Team-based projects — “Marketing Team”, “Finance Ops”, “Engineering Tools”
  • Use-case-based projects — “RFP Response”, “Contract Analysis”, “Data Enrichment”
Projects help you organize resources in a way that matches your business structure.

​
Each project contains: Agents, Use Cases, Tools, Knowledge Bases

Projects are self-contained:

Agents

AI entities with personas, models, and capabilities

Use Cases

Workflow definitions that orchestrate agents and tools

Tools

External integrations connected via MCP

Knowledge Bases

Document collections for RAG retrieval
All resources within a project can reference each other. For example:
  • An agent in the “Customer Onboarding” project can use tools from the same project
  • A use case in the “Sales Automation” project can call agents from the same project
But resources cannot cross project boundaries (with one exception: sub use cases can call use cases from other projects if you explicitly allow it).

​
Project-level access control

Projects have independent member management:
  • Add members to specific projects — You can give someone access to “Customer Onboarding” without giving them access to “Sales Automation”
  • Project roles — Admin (govern the project), Builder (create/edit resources), Operator (run and chat), or Viewer (read-only)
  • Inherited access — Org Owners automatically have access to all projects in their organization
This allows fine-grained access control without complex permission systems.

​
Independent configuration within org policies

Projects can have their own settings, as long as they comply with organization-level policies:
  • Default LLM models — Set a default model for agents in this project
  • Timeout values — Configure default timeouts for workflow activities
  • Environment variables — Project-scoped variables (API endpoints, configuration values)
Organization-level policies (quotas, security settings, approved LLM providers) still apply to all projects.

​
Member management

MagOneAI has a role-based access control (RBAC) system with three scopes: platform, organization, and project. This section is a quick orientation — for the full permission breakdown see Roles and permissions.

​
Platform

Platform-wide access. A platform-level flag that bypasses all permission checks across every organization and project, manages platform settings (email, global MCP servers), and views platform-wide stats. Reserved for the platform operator — typically 1–2 people.

​
Organization-level roles

Organization administrator. Everything an Admin can do, plus delete the organization, manage billing and SSO, manage OAuth credentials, and promote others to Owner. For business leaders accountable for the org.
Manages members and projects. Can invite/remove members, change member roles (but not grant Owner), create and delete projects, and manage organization settings.
Standard organization user. Accesses org resources and works in the default project as an Operator. Joins team projects only when explicitly added.

​
Project-level roles

Project administrator. Full control of the project: manage members, grant/revoke LLM access, manage API keys, and change project settings — on top of everything a Builder can do.
Builder and developer. Creates and edits agents, use cases, tools, knowledge bases, MCP connections, schedules, and test cases. Uses MagOneAI Studio to build workflows.
Runs and consumes. Executes workflows, chats with agents, uploads files, and triggers schedules — but cannot change configurations. This is the role that powers MagOneAI Hub consumers, and what a default-project Member receives.
Read-only. Sees project resources, executions, and analytics without the ability to run or change anything. Available in team projects.

​
How roles cascade from org to project

  • Superadmins can access everything across all organizations
  • Org Owners can access all projects within their organization
  • In the default project, your org role maps to a project role automatically: Owner → Admin, Admin → Builder, Member → Operator
  • In team projects, you must be explicitly added with a specific project role (Admin / Builder / Operator / Viewer)
Use the principle of least privilege: give users the minimum role they need. Most users should be Operators or Viewers; reserve Builder and Admin for those who build and govern, and Superadmin for platform administrators.

​
Resource sharing

Resources in MagOneAI are scoped to projects, but you can share and reuse them within certain boundaries.

​
Resources are scoped to projects

By default, all resources (agents, tools, use cases, knowledge bases) are private to the project where they were created. A project member working in “Customer Onboarding” cannot see or use resources from “Sales Automation”. This scoping provides:
  • Security — Prevent accidental access to sensitive resources
  • Organization — Keep related resources together
  • Performance — Avoid cluttering the interface with unrelated resources

​
Agents and tools can be shared across use cases within a project

Within a project, resources are reusable:
  • Agents — Create an agent once, use it in multiple use cases
  • Tools — Connect a tool once, make it available to all agents in the project
  • Knowledge Bases — Upload documents once, connect them to multiple agents
For example, in a “Customer Onboarding” project:
  • You might have a “Document Processor” agent used in KYB workflows, onboarding workflows, and compliance workflows
  • You might have a “Company Database API” tool used by multiple agents
This reusability reduces duplication and makes maintenance easier.

​
Knowledge bases are project-scoped

Knowledge bases are always scoped to a project:
  • Documents uploaded to a knowledge base in “Customer Onboarding” are not visible to “Sales Automation”
  • Agents can only access knowledge bases within their project
If you need the same documents in multiple projects, you must upload them to each project’s knowledge bases separately.
Coming soon: Cross-project resource sharing. In a future release, you’ll be able to mark specific agents or tools as “shared” at the organization level, making them available to all projects.

​
Best practices for organizing your deployment

Design your organization structure early — Before creating many projects and resources, plan your structure. Will you organize by department? By customer? By use case? The initial structure is easy to set up but harder to reorganize later.
Use projects to separate concerns — Don’t put everything in one project. Create separate projects for different teams or domains. This improves organization, access control, and performance.
Reuse agents and tools within projects — Avoid creating duplicate agents or tools. If you need the same agent in multiple workflows, reuse the existing one. This makes updates easier (change the agent once, all workflows benefit).
Assign roles carefully — Use the principle of least privilege. Most users should be Operators or Viewers. Reserve Builder/Admin for hands-on builders, Org Owner for managers, and Superadmin for platform administrators.

​
Example organizational structures

​
Scenario 1: Single company using MagOneAI internally

Organization: "Acme Corp"
├── Project: "Sales Automation"
├── Project: "Customer Support"
├── Project: "Internal Operations"
└── Project: "Compliance and Risk"
All employees belong to the same organization. Projects separate different business functions.

​
Scenario 2: SaaS provider with multiple customers

Organization: "Customer A"
├── Project: "Customer A - Onboarding"
└── Project: "Customer A - Support"

Organization: "Customer B"
├── Project: "Customer B - Onboarding"
└── Project: "Customer B - Support"

Organization: "Customer C"
├── Project: "Customer C - Onboarding"
└── Project: "Customer C - Support"
Each customer is a separate organization. This ensures complete data isolation and allows customers to bring their own LLM API keys.

​
Scenario 3: Enterprise with subsidiaries

Organization: "Acme Corp (HQ)"
├── Project: "Corporate IT"
├── Project: "HR and Onboarding"
└── Project: "Finance Ops"

Organization: "Acme Corp (EU Subsidiary)"
├── Project: "EU Sales"
└── Project: "EU Compliance"

Organization: "Acme Corp (APAC Subsidiary)"
├── Project: "APAC Sales"
└── Project: "APAC Operations"
Subsidiaries are separate organizations for data residency, compliance, or operational reasons. Each has independent projects.

​
Next steps

Admin Portal

Learn how to manage organizations, users, and security policies

MagOneAI Studio

Explore the builder interface for creating agents and workflows