Structuring and managing organizations

Factory organizations let an enterprise divide one account into teams, business units, regions, client groups, environments, or departments that need true operating boundaries. Each organization can have its own members, roles, local administration, usage limits, service accounts, and controls while still rolling up to one enterprise contract, one invoice, one identity provider connection, and one enterprise root.

Use this page when you are ready to create, configure, and operate the hierarchy in the Admin Console. For the conceptual model and design patterns, see Organization Model.

Overview

All usage, billing, and commercial attribution rolls up to the enterprise root. Organizations provide hierarchy, membership, role assignment, local administration, policy segmentation, and reporting structure, but the root remains the commercial owner.

Use organizations when you want to:

• organize teams or operating boundaries under one enterprise root;
• give different teams different admins or settings;
• keep one enterprise invoice attributed to the root organization;
• manage users through one enterprise SSO connection, with Directory Sync or UI-based membership assignment;
• prepare for users who work across multiple teams;
• apply different region, residency, usage, or policy boundaries to different groups.

Prerequisites

Before creating organizations, confirm:

• one root Factory organization is identified as the enterprise root;
• SSO is configured for the enterprise;
• the membership management approach is selected: Directory Sync for IdP-managed membership, UI-based assignment for manually managed membership, or both during migration;
• if using Directory Sync, Admin Console access is available and IdP groups exist or can be created for each organization role;
• an enterprise subscription or commit is in place so usage can roll up to one enterprise invoice;
• the planned hierarchy and initial owners are known;
• the region and data residency strategy is known for the root and each organization.

Invite new users through the enterprise root first, then assign them to the appropriate organization.

Core concepts

Enterprise root

The enterprise root is the top-level Factory organization. It owns the enterprise contract, SSO connection, optional Directory Sync connection, billing account, top-level membership, and top-level administration.

For existing enterprise customers, the existing organization usually becomes the enterprise root. This lets the customer migrate into an organization hierarchy without replacing the existing org or disrupting existing users, sessions, billing, or identity configuration.

Organization

An organization is an operating boundary inside the enterprise hierarchy. Organizations can be nested.

Acme Corp
├── Platform Services
├── Product Delivery
│   └── Regulated Workloads
└── Client Delivery

Factory can support many hierarchy shapes, but the hierarchy should be intentionally designed for clarity, administration, and long-term maintainability.

Organization path

Each organization has a slash-delimited path, such as:

Product Delivery/Regulated Workloads

The path is the human-readable hierarchy and membership label. The organization also has a stable internal ID, so renaming a team does not lose its identity. Billing and commercial attribution still roll up to the root.

Org membership and primary org selection

Users can be assigned to multiple organizations. When a user has access to more than one org, Factory provides an org selector so the user can choose which org context to use.

When a user enters Factory for the first time, or has not selected an org yet, Factory chooses the starting org in this order:

1. 1
   The root org wins when the user has root access.
2. 2
   If the user does not have root access, assigned organizations are sorted by hierarchy and name, then the first is used.
3. 3
   If the user chooses a different accessible org in the selector, that selected org becomes the active org context.
4. 4
   For multiple roles on the same org, the highest role wins: Owner, then Manager, then User.

Sessions are tied to the selected or primary org for their lifetime for product context and membership behavior. Local sessions on a user's machine can still be accessed from any org context on that machine. Usage and billing attribution still roll up to the root.

Switching organizations

Users can switch between organizations where they have access.

• In the web or desktop app, open settings, go to General, then select an organization under Organization.
• In the CLI, run /settings, open Preferences, then choose Active Organization.

What is shared across the enterprise

Organizations can be independent where teams need separation, but they intentionally share enterprise-level infrastructure.

Organizations should not be configured as separate SSO tenants or separate billing accounts.

What can differ by organization

Roles and permissions

Factory uses three role levels at each level of the hierarchy.

An enterprise owner can manage the enterprise root and create or administer organizations according to enterprise policy. An organization owner or manager can administer the organizations where they have that role, except for settings, policies, membership controls, and services where the root has declared jurisdiction.

If multiple roles apply to the same org, the most privileged role wins: Owner, then Manager, then User.

Identity, membership, and directory sync

Organizations use one enterprise SSO connection configured from the Admin Console. Membership can be assigned in two ways:

1. 1
   Directory Sync group mapping, recommended for scaled IdP-managed membership.
2. 2
   UI-based membership assignment, useful for manual setup, pilots, and customers not ready to manage organization membership through Directory Sync.

New users must be invited through the enterprise root before they can be assigned to an organization.

How directory sync works with organizations

Directory Sync manages membership and role assignment from the Admin Console. It does not replace organization creation.

Directory sync setup

When using Directory Sync:

1. 1
   Create the organization in Admin Console → Organizations.
2. 2
   Create or identify IdP groups for the organization's Owner, Manager, and User roles.
3. 3
   Open Admin Console → Security & Identity, then map each IdP group to the corresponding Factory role target.
4. 4
   Add users to the appropriate IdP groups.
5. 5
   Run or wait for Directory Sync reconciliation.
6. 6
   Confirm users can access the expected org contexts.

Example mappings:

During migration, users who need both root and organization access must be in both a root-mapped group and an organization-mapped group.

UI-based membership setup

When using UI-based membership:

1. 1
   Invite the user into the enterprise root if they are not already a member.
2. 2
   Add or update the user's organization role from the membership UI.
3. 3
   Confirm the user can select the intended org context.
4. 4
   Keep high-privilege Owner assignments small and reviewed.

Use UI-based membership for pilots, manual administration, or customers that do not want Directory Sync as the sole membership path.

Creating an organization

Enterprise admins can create organizations in the Admin Console after Factory enables organization creation for the enterprise.

UI creation flow

1. 1
   Open the Admin Console as an enterprise account owner.
2. 2
   Go to Organizations.
3. 3
   Choose the parent org for the new organization.
4. 4
   Enter the organization name.
5. 5
   Choose the region, or use the Global default.
6. 6
   Decide whether to copy root usage limits, Enterprise Controls, and membership controls.
7. 7
   Decide whether organization admins can make local changes to membership, usage limits, and Enterprise Controls.
8. 8
   Create the organization.

The user who creates the organization is automatically added as an owner of that organization. The creator should confirm they can access the new organization and that any other intended Owner or Manager assignments are in place.

Usage and billing

The enterprise receives one invoice. All usage and billing attribution is attributed to the enterprise root, even when users work in organization contexts.

Example usage summary:

Factory Standard Credits
  acme-corp:                          48,750
  acme-corp/it:                       82,140
  acme-corp/it/engineering:           36,425
  acme-corp/finance:                  19,880
 
Subtotal:                            187,195

Usage within acme-corp does not include usage within acme-corp/it. Each row represents usage in that org context, while the subtotal is the enterprise total.

Recommended guidance:

• choose the correct organization when starting new work;
• expect invoice and commercial attribution to remain at the root;
• keep long-running work in its original org unless there is a clear reason to recreate it;
• use paths that Finance, IT, security, and team admins recognize;
• review the first invoice or usage export after enabling organizations.

Usage limits

Usage limits control how much usage an org or user can consume within the enterprise subscription.

During organization creation, the enterprise admin can copy the root global usage limit into the new organization. The enterprise admin can also restrict the organization from updating its own usage limits.

After creation, when the enterprise root changes its global usage limit, the enterprise admin can choose which organizations should receive that update. Root changes are not automatically synced to every organization.

Region deployments and data residency

Organizations should follow the enterprise's data residency and deployment strategy. At creation, the admin can declare the organization's region. If no region is declared, the organization defaults to Global.

Region planning matters for:

• where session data is stored;
• which deployment serves the org;
• which integrations and network policies apply;
• how support, debugging, and audit workflows are routed;
• whether users can move work between orgs without residency concerns.

If a customer wants independent data residency for a specific organization, declare that region during creation and document the intended data boundary.

Service accounts, API keys, and automation access

Automation access should be scoped to the organization where the automation operates.

Service accounts

Service accounts are the preferred model for non-human automation. They should be created and assigned according to the team or workflow they represent.

Guidance:

• create service accounts in the organization that owns the workflow;
• avoid using a root-level service account for team-specific automation unless the workflow truly operates enterprise-wide;
• review service account ownership when moving a workflow between organizations;
• include service accounts in access reviews alongside human owners and managers.

API keys

API keys are legacy and expected to be replaced by service accounts. While API keys still exist, treat them as org-scoped credentials.

Guidance:

• create API keys only in the organization that owns the integration;
• do not reuse a root API key for organization-specific workflows;
• prefer service accounts for new automation;
• track any remaining API keys during migration so they can be replaced later;
• rotate or remove API keys when a team, integration, or organization changes ownership.

Automation ownership worksheet

Enterprise Controls and membership controls

Each organization can have local controls such as managed settings, security policy, usage limits, and membership administration where root restrictions allow it.

During organization creation, the enterprise admin can copy root Enterprise Controls into the new organization. The enterprise admin can also restrict the organization from making its own Enterprise Control changes, usage-limit changes, or membership-control changes.

After creation, when the enterprise root changes Enterprise Controls, global usage limits, or membership controls, the enterprise admin can choose which organizations should receive that update.

Enterprise Controls include:

• model allowlists and blocklists;
• usage limits;
• membership controls;
• custom model access and user model policies;
• max autonomy level and session defaults;
• command allowlists and denylists;
• MCP, network, and sandbox policy;
• cloud session sync and Droid Shield;
• member visibility;
• API key creation;
• managed computer availability;
• session retention.

Organization admins can customize local settings and membership behavior when the enterprise admin has not restricted local changes. When local changes are restricted, root-managed fields should be shown as read-only with the root identified as the managing org.

Copying root settings

Copying root settings is useful when:

• the organization should begin with the same model policy;
• command controls should match the root baseline;
• membership controls should match the root operating model;
• integration defaults should be the same;
• the team wants a baseline before local customization.

Starting from defaults is useful when:

• the organization is a pilot or sandbox;
• the team has a different risk profile;
• the root has legacy settings that should not carry forward;
• the customer wants to rebuild policy intentionally.

Settings copied at creation are a starting point. If the enterprise root later changes global usage limits, Enterprise Controls, or membership controls, the enterprise admin chooses which organizations should receive that update.

Enterprise controls review checklist

• Which controls must apply enterprise-wide?
• Which controls should differ by risk profile, region, or workflow?
• Which usage limits should be copied from the root?
• Which organizations should be restricted from changing their own usage limits?
• Which membership controls should be managed by the root?
• Which organizations can manage custom models or BYOK?
• Which organizations can use MCP servers?
• Which organizations can create service accounts or legacy API keys?

Recommended rollout

Step 1: design the hierarchy

Start with the boundaries that must differ, not the department chart. Create an organization when a group needs distinct membership, administration, policy, region, credentials, integrations, or usage limits.

Use department-based organizations only after this boundary review. A department should become an organization when it needs different owners, members, credentials, residency, policy, or spend controls, not only because it appears as a department in the HR system.

Step 2: confirm enterprise prerequisites

Confirm the root organization, SSO, membership approach, billing expectation, region plan, service accounts, and legacy API key ownership before enabling broad access.

Step 3: create organizations

Create each organization under its intended parent. Organization names must be unique among siblings. For each organization, decide whether it should copy root settings, allow local changes, declare a region, and own any service accounts, API keys, integrations, or automations.

Step 4: configure roles and membership

Configure User, Manager, and Owner access through Admin Console Directory Sync mappings, UI-based assignment, or both during migration.

Step 5: pilot with a small group

Before broad rollout, assign users to two or three organizations and confirm:

• users can choose the correct org when starting work;
• usage and billing attribution remain at the root;
• selected org context appears as expected in product surfaces;
• role gates, membership controls, and Enterprise Controls behave as expected;
• region and residency expectations are met;
• service accounts and legacy API keys are scoped to the correct org.

Step 6: expand rollout

After pilot validation, create the remaining organizations, map remaining IdP groups or assign users in the UI, re-scope credentials where needed, notify users how to select the right org, and monitor root attribution during the first billing period.

Migration behavior

Enabling organizations does not require replacing the existing organization. The existing org becomes the enterprise root.

Migration behavior:

• existing users can continue working in the root org;
• users who should move into organizations can be assigned to both the root org and their target organization during migration;
• with Directory Sync, the user must be in both a root-mapped group and an organization-mapped group;
• with UI-based membership, the user must first be invited to or retained in the enterprise root, then assigned to the target organization;
• existing sessions keep their existing org context;
• new sessions can use organization context for membership, administration, and policy behavior;
• all usage and billing attribution remains at the root.

Recommended migration strategy:

1. 1
   Confirm the existing org is the enterprise root.
2. 2
   Create the target hierarchy under the root.
3. 3
   Copy root global usage limits, Enterprise Controls, and membership controls where they are a useful starting point.
4. 4
   Decide which organizations should be restricted from changing their own limits, controls, and membership settings.
5. 5
   Configure membership through Admin Console Directory Sync mappings or UI-based assignment.
6. 6
   Add migrating users to both the root org and their target organization for backward compatibility.
7. 7
   Ask users to switch into the appropriate organization when they are ready to create new work there.
8. 8
   Pilot a small group and confirm org switching, root attribution, membership controls, and Enterprise Controls.
9. 9
   Re-scope API keys and service accounts to the intended owning org where needed.
10. 10
    Expand membership gradually and monitor root-attributed usage plus selected org context during the first billing period.
11. 11
    If desired, remove users from the enterprise root after they have fully moved into their intended organizations.

FAQ