# Identity & Access

Manage who can run Droid with SSO, Directory Sync, roles, service accounts, agent profiles, and Factory API keys.

Identity and access management controls **who can run Droid**, in which environments, and under what policies. This page covers the identity model and roles, Single Sign-On and SCIM directory sync, and service accounts and agent profiles for work that runs on your organization's behalf.

---

## Identity model

Every Droid run is associated with several dimensions of identity:

| Identity dimension | What it controls |
| --- | --- |
| User or machine identity | Human developers authenticate via SSO (SAML/OIDC), inheriting their directory groups and roles. Automation (CI/CD, scheduled jobs, scripts) runs under **service accounts** with their own API keys. |
| Org / project / folder | The active repo and `.factory/` folders determine the **org, folder, and project context**. Policies at these levels decide which models, tools, and integrations Droid may use. |
| Runtime environment | Whether Droid runs on a laptop, in a CI runner, or in a sandboxed VM is captured as environment attributes. Policies can treat these differently, such as allowing higher autonomy only in CI or sandboxes. |
| Session metadata | Each Droid session records metadata such as session ID, CLI version, and git branch, which is available for audit and OTEL telemetry. |

Identity and environment information feed two systems: **policy evaluation** (managed settings use identity and context to decide which configuration applies; see [Enterprise Controls & Managed Settings](/enterprise/hierarchical-settings-and-org-control)) and **telemetry and audit** (OTEL metrics and audit events carry attributes such as `user.id`, `organization.id`, and `session.id`; see [Compliance & Audit](/enterprise/compliance-audit-and-monitoring)).

---

## Roles

Factory organizations have three membership roles: **User**, **Manager**, and **Owner**. Each role includes the permissions of the roles below it, and role information flows from your IdP (via SSO claims or SCIM groups) into Factory.

| Role | Capabilities |
| --- | --- |
| **Owner** | Full control of the organization, including billing, deletion, all settings, members, and API keys. |
| **Manager** | Manage members, organization settings, API keys, service accounts, and agent profiles. Manage org-level `.factory` policy (models, command allow/deny lists, telemetry, autonomy ceilings). |
| **User** | Standard member. Run Droid locally, in IDEs, in CI, or via team scripts, and customize personal preferences in `~/.factory/`, but cannot change any setting locked at the org, folder, or project level. |

### User

Users can access Factory and use the core product experience. This role fits members who create and work with Droid sessions, use their personal workspace, and view information relevant to their own activity. Users can create and share their own sessions, view their own analytics and activity, view the organization's usage in Settings, manage their own personal settings and connections, view other members when the organization allows member visibility, and manage the [service accounts](#service-account-owners) and [agent profiles](/enterprise/agent-profiles#owners) they have been made an owner of. Users cannot manage organization-wide settings, billing, members, or shared administrative controls.

### Manager

Managers can do everything Users can, plus manage most day-to-day organization administration. This role fits team leads, workspace admins, or operations owners who keep the organization running. Managers can invite, update, and remove members; manage organization integrations and repositories; view organization-level analytics dashboards and full usage data, including global and per-user limits; manage usage limits and usage-related controls; manage organization settings and enterprise controls; manage service accounts and shared computer resources; create, edit, duplicate, and delete [agent profiles](/enterprise/agent-profiles) and assign them to delegation apps; and purchase or configure extra usage where available. Managers cannot manage owner-only billing, payment, or identity-administration actions.

### Owner

Owners can do everything Managers can, plus access the most sensitive organization controls. This role fits the person or team ultimately responsible for the Factory account. Owners can manage billing details and payment methods, access the billing portal, start or change high-impact subscription settings, configure SSO, domain verification, and directory sync where available, view the organization's audit log (an Enterprise feature available to organization owners), complete account onboarding or plan setup steps that require account ownership, and manage owner-only usage and billing controls. Owners can also change, lock, and unlock locked service accounts and agent profiles even when they are not one of their owners. Only Owners can lock or unlock the Org Default agent profile.

### Organization roles and resource owners

Service accounts and agent profiles can also have their own **owners**: individual members who manage that one resource. Being an owner of a resource is separate from the organization **Owner** role.

| Action on a service account or custom agent profile | User | User who owns it | Manager | Owner |
| --- | --- | --- | --- | --- |
| Create | No | No | Yes | Yes |
| Edit, delete, or change owners and access (unlocked) | No | Yes | Yes | Yes |
| Edit, delete, or change owners and access (locked) | No | Yes | No | Yes |
| Lock or unlock | No | Yes | No | Yes |
| Duplicate an agent profile | No | No | Yes | Yes |
| Assign agent profiles to delegation apps | No | No | Yes | Yes |

A Manager or Owner who is also an owner of a resource has both sets of permissions. See [service account owners](#service-account-owners) and [agent profile owners](/enterprise/agent-profiles#owners) for details.

Exact access can vary based on your organization's plan, enabled features, and administrative settings. When in doubt, assign the lowest role that gives a member the access they need.

The managed settings engine enforces what each role can effectively change. See [Enterprise Controls & Managed Settings](/enterprise/hierarchical-settings-and-org-control) for the exact precedence rules.

<LabeledDivider label='Provisioning' />

## Domains, SSO, and SCIM

Factory uses **WorkOS** for enterprise identity, supporting domain verification, SSO (SAML/OIDC), and Directory Sync (SCIM). Contact your Factory representative or [support@factory.com](mailto:support@factory.com) to start setup; you will receive a secure setup link to configure your identity provider.

<Info>
  WorkOS handles the technical configuration. The setup wizard generates the
  SAML/OIDC parameters and SCIM endpoint for your specific provider, so you do
  not configure ACS URLs, certificates, or attribute mappings by hand. For
  provider-specific screenshots and steps, follow the WorkOS admin guide linked
  in your setup flow.
</Info>

### Domain verification (required first)

Domain verification proves your organization owns specific email domains and is a **prerequisite for SSO**. You add each domain, WorkOS issues a TXT record, and you add it to your DNS; verification typically completes within 1-24 hours depending on propagation.

Once a domain is verified:

{/* sweep-allow: term-bullets */}

- **Automatic claiming**  -  existing and new users with that email domain join your organization.
- **Identity governance**  -  you can require SSO for domain users and apply org security policies (MFA, session controls, IP restrictions) consistently.
- **SSO readiness**  -  you can enable SSO for the verified domains.

Verify your primary domain first, then add subsidiary, legacy, or alias domains. Each domain is verified separately but shares the same organizational policies.

<Warning>
  SSO cannot be enabled without verified domains. All users authenticating via
  SSO must have email addresses from verified domains.
</Warning>

### Single sign-on (SAML / OIDC)

With SSO enabled, users sign in through your IdP instead of a password:

1. The user chooses "Sign in with SSO" and is redirected to your IdP.
2. They authenticate with corporate credentials.
3. The IdP returns a SAML assertion or OIDC token to Factory.
4. The user is authenticated and, if **Just-In-Time (JIT) provisioning** is enabled, created on first login with a profile populated from the IdP claims.

WorkOS supports all major IdPs (Okta, Microsoft Entra ID, Google Workspace, OneLogin, Ping, JumpCloud) plus generic SAML 2.0 and OIDC. Organizations that do not use SSO can use passwordless magic-link sign-in, which is also useful for external collaborators.

### Directory sync (SCIM)

SSO controls **how users authenticate**; SCIM controls **which users and groups exist** in Factory. With Directory Sync enabled through your IdP:

- Adding a user to a synced directory group **provisions** them in Factory.
- Updating directory attributes **syncs** to Factory.
- Removing a user from the directory **deactivates** their access (soft delete  -  work history is preserved).
- Group membership changes propagate automatically, so RBAC stays defined in your IdP.
- Synced groups can carry monthly usage limits for their members through [User Groups](/enterprise/user-groups).
- Synced groups can control who can use [agent profiles](/enterprise/agent-profiles#access) and [service accounts](#service-account-access).

Sync only the groups that need Factory access (for example, `factory-*` groups), and keep the SCIM token secret  -  store it only in your IdP's application configuration.

#### Group-to-role mapping

Map your directory groups to Factory's three roles. WorkOS role slugs resolve as follows: `owner` maps to **Owner**; `admin` or `manager` maps to **Manager**; every other slug maps to **User**.

| Example IdP group | Factory role |
| --- | --- |
| `factory-owners` | Owner |
| `factory-managers` (or `factory-admins`) | Manager |
| `factory-developers`, `factory-contractors`, any other group | User |

Use descriptive, prefix-based group names (`factory-*`) so IdP configuration stays maintainable and auditable alongside your other enterprise apps.

### Data priority and conflict resolution

When a user exists from multiple sources (SCIM, SSO JIT, manual invite, API):

1. **Directory Sync data wins**  -  SCIM attributes overwrite other sources.
2. **Email-based matching**  -  users are matched by email, case-insensitively (`John.Doe@company.com` equals `john.doe@company.com`).
3. **Custom data is preserved**  -  Factory-specific fields not present in your directory are retained.
4. **Soft deletes only**  -  removed users are deactivated, not deleted.

When both SSO JIT and SCIM are enabled, choose one primary method to avoid duplicate-user conflicts: either disable JIT and require directory provisioning (directory-first), or use JIT for creation and the directory for updates (SSO-first).

### Troubleshooting

<Troubleshooting>
  <TroubleshootingItem title="Login loops or failures">
    Verify ACS / redirect URLs match what Factory provided and confirm certificates have not expired or rotated.
  </TroubleshootingItem>

  <TroubleshootingItem title="User lands in the wrong org or role">
    Check group memberships and the group-to-role mapping, and ensure the intended groups are included in SAML assertions or ID tokens.
  </TroubleshootingItem>

  <TroubleshootingItem title="Provisioning is not working">
    Confirm SCIM is enabled in both Factory and your IdP, and check your IdP's SCIM logs for invalid token, URL, or schema errors.
  </TroubleshootingItem>
</Troubleshooting>

Keep a small pilot group for initial rollout, and manage all role changes and access reviews in your IdP to reuse existing governance.

<LabeledDivider label='Automation and endpoints' />

## Service accounts

Service accounts are non-human identities that automate work on behalf of your organization: CI/CD pipelines, scripts, Slack automations, or Droid Computers. Use one when a workload should belong to your organization instead of a specific teammate. A service account authenticates with a Factory API key and runs as its own principal, so sessions, computers, billing, and audit events are attributed to it rather than a human user.

Every [agent profile](/enterprise/agent-profiles) also has its own service account. The profile decides how Droid works, and its service account decides who Droid is: work that runs on the profile uses that account's Git credentials, connectors, secrets, and computers. A profile's service account is created with the profile and managed from the profile editor. This section covers service accounts you create yourself.

| Step | What to configure |
| --- | --- |
| Create a service account | Add a stable identity from **Settings → Identity → Service Accounts**. Give it a clear name and description. Only **Owner** and **Manager** roles can create service accounts. |
| Generate API keys | Create keys for scripts, CI jobs, and other automated workloads. A key value is shown **only once** at creation  -  copy it and store it securely. |
| Attach Droid Computers | Create Droid Computers owned by the service account so long-running work continues under the same identity instead of a teammate's account. |
| Configure Git access | For GitHub and GitHub Enterprise Server, install your organization's **GitHub App** on the repositories the service account needs; no token is needed. For GitLab and GitLab Self-Hosted, add a token owned by the service account in its **Git Credentials**. See [repository access for the service account](/delegations#repository-access-for-the-service-account) and [Self-Managed Source Control](/enterprise/self-managed-scm). |

Business and Enterprise plans can create service accounts for any workload. Individual plans and the Teams plan cannot create standalone service accounts. They get the service account of the [Org Default agent profile](/enterprise/agent-profiles#the-org-default-agent-profile), which serves [Delegations](/delegations), and one for each custom agent profile.

A service account must be **active** to authenticate. Marking one inactive or deleting it causes new requests with its keys to fail, so move or restart dependent workloads first. Names are immutable identifiers  -  create a new account if you need a different name.

Managers and Owners can see and manage every service account in the **Service Accounts** section of <a href="https://app.factory.ai/settings/identity">**Settings → Identity**</a>. A User who is an [owner](#service-account-owners) of a service account also sees the Service Accounts section and can manage the accounts they own. See [organization roles and resource owners](#organization-roles-and-resource-owners).

### Service account owners

Owners are people who manage a specific service account without needing the Manager role. Owners can view and edit the account, including its API keys, Git credentials, connectors, secrets, computers, access, and lock. They can also change its owners and delete it.

- Owners must be active members of the organization. Directory groups cannot be owners.
- An account can have up to 50 owners.
- Creating a service account does not make you one of its owners. Add owners from the account's settings.
- Owners who are not Managers cannot create new service accounts.

The service account of an agent profile has no owner list of its own. The profile's owners manage it. See [agent profile owners](/enterprise/agent-profiles#owners).

### Lock a service account

Lock a service account to stop other Managers from changing it. While an account is locked, only its owners and organization Owners can change its settings, status, owners, or access, manage its API keys, Git credentials, connectors, secrets, or computers, or delete it. Other Managers see it as read-only.

Only the account's owners and organization Owners can lock or unlock it. You can lock an account that has no owners after confirming; until someone adds an owner, only organization Owners can change it.

The service account of an agent profile follows the profile's lock.

### Service account access

Access controls who can use a service account: who can choose it in the **Run as** picker for an automation, who can act as it from the session composer, and who can use its computers.

- **Everyone:** every member of the organization can use the account.
- **Specific people and groups:** only the people you list and members of the directory groups you select can use it. Managers and the account's owners can always use it.

People without access do not see the account in **Run as** pickers. Directory groups come from [directory sync](#directory-sync-scim).

The access of an agent profile's service account is set in the profile editor. Org Default's account is always open to everyone.

### Computer secrets

Computer secrets are environment variables for a service account's managed computers. They are available on Factory-hosted deployments. Open them from **Secrets** in an active service account's actions, or from the **Secrets** section of an [agent profile](/enterprise/agent-profiles#configure-an-agent-profile).

- Service account secrets are added to your organization's computer secrets. If a name matches an organization secret, the service account's value is used.
- Existing computers keep their current environment until they are refreshed and restarted.
- Values are write-only. You cannot read a value back after saving it.
- Names can be up to 128 characters, must start with an uppercase letter or underscore, and can contain only uppercase letters, digits, and underscores. Some names are reserved and cannot be used.
- Values must be 1 to 10,000 characters.

Managers, Owners, and the account's owners can manage secrets. The account's lock applies. Inactive accounts cannot have their secrets changed.

<Warning>
  Service accounts never inherit organization OAuth credentials for source
  control. If a GitHub or GitHub Enterprise Server repository does not have a
  matching GitHub App installation, or a GitLab or GitLab Self-Hosted repository
  has no service-account token, Factory stops the operation instead of running
  it with a human user's access.
</Warning>

### Service account key hygiene

| Practice | Why it matters |
| --- | --- |
| Use short-lived keys when possible | Set expiration dates for keys used in temporary automation to limit blast radius if a key is exposed. Organizations can also set a maximum lifetime for new keys, including service account keys. See [API key lifetime limit](/enterprise/hierarchical-settings-and-org-control#api-key-lifetime-limit). |
| Rotate keys regularly | Create a new key, update the workload, then revoke the old key. |
| Lock shared accounts | Add owners and lock accounts that production workloads depend on, so only the people responsible for them can change them. |
| Delete when finished | Deleting a service account revokes its access and cleans up owned Factory resources where possible. |

## Agent profiles

An [agent profile](/enterprise/agent-profiles) is the saved setup Factory uses when Droid works on your organization's behalf, such as when a teammate delegates work from Slack, Linear, Jira, Microsoft Teams, or Google Chat. Each profile has its own service account, plus a model, custom instructions, plugins, and compute.

The service account decides *who* the work runs as and what it can reach. The agent profile decides *how* the work runs. Shared sessions run as the profile's service account, never as the teammate who asked or the administrator who edited the profile.

Every eligible organization has a built-in **Org Default** agent profile, and Managers and Owners on a paid plan can create custom profiles for specific teams. Manage them under <a href="https://app.factory.ai/settings/identity">**Settings → Identity**</a> → **Agent Profiles**. See [agent profiles](/enterprise/agent-profiles) for what each setting controls.

---

## Devices, environments, and workspace trust

Because Droid is a CLI, it can run on developer laptops, remote dev servers, CI runners, and hardened VMs or devcontainers. Enterprises typically combine Droid with endpoint management and environment-aware policy:

### Endpoint and workspace controls

| Control | Recommended use |
| --- | --- |
| Endpoint and MDM controls | Use Jamf, Intune, or other MDM solutions to control where Droid binaries can be installed, which users can run them, and which configuration files they can read. Common patterns: run only under managed user accounts, restrict configuration directories to corporate-managed volumes, and enforce OS-level disk encryption and screen lock. |
| Workspace trust | Treat Droid as trusted only in known repositories. Pin Droid to specific paths or repos, require elevated approval or sandboxed environments for untrusted code, and use project-level `.factory/` folders to mark which repos are "Droid-ready." |
| Environment-aware policies | The same developer may run Droid on a laptop, in CI, or in an isolated container. Policies can allow higher autonomy or more powerful tools **only** inside devcontainers or CI runners, restrict network access on laptops, and tag OTEL telemetry with environment attributes for environment-specific alerting. |

<RelatedLinks>
  <RelatedLink href="/enterprise/agent-profiles" title="Agent profiles">
    Configure the identity, compute, and behavior of Droid sessions that run on your organization's behalf.
  </RelatedLink>
  <RelatedLink href="/delegations" title="Delegations">
    Delegate work to Droid from Slack, Linear, Jira, Microsoft Teams, and Google Chat.
  </RelatedLink>
  <RelatedLink href="/enterprise/hierarchical-settings-and-org-control" title="Enterprise Controls & Managed Settings">
    Define which roles can change which policy levels in the settings hierarchy.
  </RelatedLink>
  <RelatedLink href="/enterprise/compliance-audit-and-monitoring" title="Compliance & Audit">
    Map identity and access events to audit trails and compliance workflows.
  </RelatedLink>
</RelatedLinks>
