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 — Project Owner (full control) or Project Member (create/edit resources)
  • 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 clear separation between platform administration, organization management, project work, and end-user access.

​
Organization-level roles

Platform-wide access. Can manage all organizations, users, LLM providers, and security policies. SuperAdmins have access to the Admin Portal and can create/delete organizations. This role is typically reserved for IT administrators or the platform operator.
Organization administrator. Can manage users, projects, and resources within their organization. Org Owners can invite members, create projects, and configure organization settings but cannot access other organizations. This role is for business leaders or team managers.
Builder and developer. Can create and edit agents, workflows, tools, and knowledge bases within projects they have access to. Org Members use MagOneAI Studio to build and deploy AI workflows. This role is for hands-on builders and developers.

​
Project-level roles

Project administrator. Has full control over a specific project, including member management, resource creation, editing, and deletion. Project Owners can invite members to the project and configure project settings.
Project contributor. Can create and edit resources (agents, use cases, tools, knowledge bases) within a specific project. Access is scoped to assigned projects only — Project Members cannot see or modify resources in other projects unless explicitly granted access.

​
End User role

Consumer role. Can interact with deployed workflows via MagOneAI Hub (the chat interface) but cannot access MagOneAI Studio or create/edit workflows. This role is for employees, customers, or partners who need to use AI workflows without building them.

​
How roles cascade from org to project

Role inheritance works as follows:
  • SuperAdmins can access everything across all organizations
  • Org Owners can access all projects within their organization
  • Org Members must be explicitly added to projects to access them
  • Project Owners and Project Members have access only to their assigned projects
  • End Users have no access to MagOneAI Studio — they can only use MagOneAI Hub
Use the principle of least privilege: give users the minimum role they need. Start with End User or Project Member, and elevate to Org Owner or SuperAdmin only when necessary.

​
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 Project Members or End Users. Reserve 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