# Structuring and managing organizations

Create organizations, assign users, configure Directory Sync mappings, manage usage limits, and plan migration under one enterprise root.

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](/enterprise/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.

<Info>
  Directory Sync is recommended for scaled IdP-managed membership, but it is
  not required. Customers can also assign organization membership in the UI.
</Info>

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.

```text title="organization-hierarchy.txt"
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:

```text
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. The root org wins when the user has root access.
2. If the user does not have root access, assigned organizations are sorted by hierarchy and name, then the first is used.
3. If the user chooses a different accessible org in the selector, that selected org becomes the active org context.
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.

| Area | Enterprise-wide behavior |
| --- | --- |
| Billing | One billing account and invoice for all orgs. |
| Contract and subscription | Managed on the enterprise root. |
| Attribution | All usage, billing, and commercial attribution goes to the root. |
| SSO | One WorkOS organization and SSO connection. |
| Directory Sync | Optional. When used, one directory connection serves the enterprise. |
| Identity provider setup | One IdP integration with groups mapped to Factory roles. |
| Root-managed controls | Root controls can apply enterprise controls, usage limits, and membership restrictions to selected organizations. |

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

## What can differ by organization

| Area | Organization behavior |
| --- | --- |
| Members | Users can belong to multiple organizations. One primary assignment is recommended when possible. |
| Roles | User, Manager, and Owner roles apply per assigned organization. |
| Usage | Product context can be tied to the selected org, while commercial attribution rolls up to the root. |
| Usage limits | Local usage-limit settings can exist where allowed. Root global limits can be copied during creation and later applied to selected organizations. |
| Enterprise Controls | Settings can be customized locally unless the enterprise root restricts organization changes. |
| Membership controls | Membership can be managed locally unless the enterprise root restricts local membership changes. |
| Region / data residency | An organization region can be declared at creation. The default is Global. |
| Service accounts | Automation identities are scoped to the organization where they operate. |
| API keys | Legacy API keys remain org-scoped while they exist. Service accounts are the preferred path. |
| Admin responsibilities | Organization owners and managers can administer their organization according to their role and any root-managed restrictions. |

## Roles and permissions

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

| Role | Typical permissions |
| --- | --- |
| Owner | Manage settings, members, billing-visible views, and high-privilege admin actions. |
| Manager | Manage day-to-day team settings and members where allowed. |
| User | Use Factory products in the assigned organization. |

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. Directory Sync group mapping, recommended for scaled IdP-managed membership.
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.

| Question | Answer |
| --- | --- |
| Do I need to enable a separate "set up organization via Directory Sync" configuration? | No. Use the Admin Console to enable SSO and Directory Sync for the enterprise, then map IdP groups to Factory role targets for the root and any organizations. |
| Can Directory Sync create organizations? | No. Create organizations in the Admin Console first. Directory Sync then assigns users to the role targets Factory exposes for those organizations. |
| How does Directory Sync pick up an organization created in the Admin Console? | After the organization exists, Factory creates role targets for that organization. Map IdP groups to those role targets from the Admin Console identity flow, then run or wait for Directory Sync reconciliation. |
| What if a role target is not visible yet? | Reopen the Admin Console identity setup surface or contact Factory support. Do not create a separate SSO tenant for the organization. |

### Directory sync setup

When using Directory Sync:

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

Example mappings:

| IdP group | Factory access |
| --- | --- |
| `Acme Factory Owners` | Owner of `Acme Corp` |
| `Product Delivery Factory Users` | User of `Product Delivery` |
| `Regulated Workloads Factory Managers` | Manager of `Product Delivery/Regulated Workloads` |
| `Client Delivery Factory Users` | User of `Client Delivery` |

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. Invite the user into the enterprise root if they are not already a member.
2. Add or update the user's organization role from the membership UI.
3. Confirm the user can select the intended org context.
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. Open the Admin Console as an enterprise account owner.
2. Go to **Organizations**.
3. Choose the parent org for the new organization.
4. Enter the organization name.
5. Choose the region, or use the Global default.
6. Decide whether to copy root usage limits, Enterprise Controls, and membership controls.
7. Decide whether organization admins can make local changes to membership, usage limits, and Enterprise Controls.
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:

```text
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.

| Level | Meaning |
| --- | --- |
| Global level | A default usage limit policy for the organization. |
| Per-user level | A user-specific usage limit that can differ from the default. |

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.

| Choice | Behavior |
| --- | --- |
| Default to Global | The organization uses the Global region. |
| Declare a specific region | The organization uses the selected deployment region for its own data and requests. |
| Mix regions within a hierarchy | Supported as an intentional setup choice when different teams have different residency needs. |

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.

| Service account | Suggested scope |
| --- | --- |
| `product-delivery-ci` | `Product Delivery` |
| `regulated-reporting` | `Product Delivery/Regulated Workloads` |
| `platform-automation` | root org or `Platform Services` |

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

| Workflow | Owning organization | Human owner | Credential type | Notes |
| --- | --- | --- | --- | --- |
| CI session creation | `Product Delivery` |  | Service account |  |
| Regulated reporting | `Product Delivery/Regulated Workloads` |  | Service account |  |
| Legacy integration |  |  | API key | Replace with service account. |

## 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.

<Warning>
  Root changes are not automatically synced to every organization.
  Enterprise admins choose which organizations should receive later root
  updates.
</Warning>

### Enterprise controls review checklist

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

## 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.

| Organization path | Owners | Managers | Users source | Notes |
| --- | --- | --- | --- | --- |
| `Platform Services` | Platform leadership | Platform leads | Directory Sync group | Shared services, defaults, and administrative ownership. |
| `Product Delivery` | Engineering leadership | Team leads | Directory Sync group or UI assignment | Standard product work with shared repositories and integrations. |
| `Product Delivery/Regulated Workloads` | Security or compliance owner | Regulated workload leads | Directory Sync group | Stricter controls, regional deployment, BYOK, or customer-hosted inference. |
| `Client Delivery` | Services leadership | Engagement leads | Directory Sync group or UI assignment | Separate client credentials, repositories, service accounts, or automations. |

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

## FAQ

<FAQ>
  <FAQItem title='Can users belong to multiple organizations?'>
    Yes. Users can belong to multiple organizations. To limit confusion and administrative overhead, assign each user to one primary organization when possible.
  </FAQItem>
  <FAQItem title='Is Directory Sync required?'>
    No. Directory Sync is recommended for scaled IdP-managed membership, but customers can also assign organization membership in the UI.
  </FAQItem>
  <FAQItem title='Can an organization invite users?'>
    No. New users must be invited through the enterprise root. After the user exists in the enterprise root, they can be assigned to the appropriate organization.
  </FAQItem>
  <FAQItem title='Can the root org still be used?'>
    Yes. The root org is still a usable org. Usage and billing attribution goes to the root even when users work in another organization context.
  </FAQItem>
  <FAQItem title='Does each organization get a separate invoice?'>
    No. The enterprise receives one invoice attributed to the root organization.
  </FAQItem>
  <FAQItem title='Does each organization need a separate SSO connection?'>
    No. Organizations use one enterprise SSO connection.
  </FAQItem>
  <FAQItem title='Can organizations be in different regions?'>
    Yes. An organization's region can be declared at creation time. If no region is declared, it defaults to Global.
  </FAQItem>
  <FAQItem title='Should service accounts live at the root or organization level?'>
    Service accounts should live where the workflow operates. Use a root-level service account only for enterprise-wide workflows. Use an organization service account for team-specific automation, integrations, and CI workflows.
  </FAQItem>
  <FAQItem title='What happens to old sessions?'>
    Existing sessions continue to use their original org context. New sessions should be created in the intended organization context. Usage and billing attribution still goes to the root.
  </FAQItem>
  <FAQItem title='Can root controls override organization controls?'>
    Yes, when root management is enabled for a control area. Organization admins can make local changes only where the enterprise root allows them.
  </FAQItem>
  <FAQItem title='Are copied settings kept in sync?'>
    No. Copying settings during organization creation does not automatically sync future root changes to every organization. Later root changes affect only the organizations the enterprise admin selects for that update.
  </FAQItem>
</FAQ>

<RelatedLinks>
  <RelatedLink href='/enterprise/organization-model' title='Organization Model'>
    Design the enterprise root, organization hierarchy, and operating boundaries.
  </RelatedLink>
  <RelatedLink href='/enterprise/enterprise-admin-console' title='Admin Console'>
    Use the Admin Console to manage directory, organizations, billing, and identity.
  </RelatedLink>
  <RelatedLink href='/enterprise/identity-and-access' title='Identity & Access'>
    Configure SSO, Directory Sync, roles, service accounts, and API keys.
  </RelatedLink>
  <RelatedLink href='/enterprise/hierarchical-settings-and-org-control' title='Enterprise Controls'>
    Manage settings, model access, safety policy, and usage controls.
  </RelatedLink>
</RelatedLinks>