# Projects ## Introduction A project is a dashboard-level grouping of environments. Every WorkOS team is organized as a hierarchy: ```txt Team └─ Project └─ Environment (staging / production) └─ Application (web / desktop / mobile) ``` Every team starts with a single project that contains a staging and a [production environment](https://workos.com/docs/authkit/environments). Projects let you keep more than one of these setups under a single WorkOS team, each with its own environments and project-level configuration.  ## When to use a project Create a separate project when you need a fully isolated setup that still lives under one WorkOS team. Common reasons include: - **Distinct products or business units**, each with their own staging and production environments. - **Separate feature flags and other project-level configuration** that shouldn't be shared across products. If you only need to isolate configuration between development and staging, add an [environment](https://workos.com/docs/authkit/environments) to your existing project instead of creating a new project. And if you need to support several client surfaces (such as a web app and a mobile app) that share the same users, use [applications](https://workos.com/docs/authkit/applications) within a single environment. ## Projects vs. environments vs. applications These three concepts solve different problems. Each row below describes one of them. | Concept | What it is | Use it when | User base | | ----------- | ----------------------------------------------------------------------- | ------------------------------------------------------------ | ------------------------------------------------------ | | Project | A grouping of the environments that belong to one product | You manage more than one product under a single team | Inherited from each environment; projects only group them | | Environment | An isolated instance of your product, such as staging or production | You need to build and test without affecting real users | Isolated from every other environment | | Application | A single client of your product (web, mobile, or desktop) within an environment | You have multiple clients that should share one set of users | Shared with the other applications in the environment | When deciding which to reach for: - Need separate sign-in surfaces that share one user base? Use [applications](https://workos.com/docs/authkit/applications). - Need somewhere isolated to develop and test before going live? Add an [environment](https://workos.com/docs/authkit/environments). - Need a fully separate setup — its own configuration and staging and production environments — under one team? Create a project. ## Project-level configuration Most configuration is scoped to a single environment and doesn't carry over between environments. API keys, organizations, connections, users, and webhook endpoints all belong to one environment. A handful of settings are instead shared across every environment in a project: - [Feature flags](https://workos.com/docs/feature-flags) - [Audit Logs schema](https://workos.com/docs/audit-logs/metadata-schema) - [Custom email domains](https://workos.com/docs/custom-domains/email) Because these settings live at the project level, they affect whether an environment can be transferred. An environment can't be moved out of a project that has any of this configuration until WorkOS supports copying it to the new project. See [transfer environments from another project](#transfer-environments-from-another-project). Branding is configured per environment, so each environment can have its own logo, colors, and theme. To avoid setting up branding from scratch in a new environment, you can [copy it from another environment](https://workos.com/docs/authkit/branding). ## Creating a project Create a project from the [WorkOS Dashboard](https://dashboard.workos.com/). Give it a name (visible only to your team and editable at any time), then choose how to populate it: start from scratch with new environments, or transfer existing environments from another project. ### Start from scratch Starting from scratch provisions a brand new staging environment, and optionally a production environment. Staging is always included; production is added by default but can be left off and unlocked later by adding billing information. You can add more environments after the project is created.  ### Transfer environments from another project Instead of starting fresh, you can move existing environments into the new project. Select a single source project, then choose one or more of its environments to transfer. A few rules apply: - All transferred environments must come from the **same source project**. You can't pull environments from several projects at once. - The source project must **keep at least one environment**. You can't move all of them out. - The source project can't have [project-level configuration](#project-level-configuration) that isn't yet copyable. Transferring out of a project with feature flags, an Audit Logs schema, or custom email domains isn't supported yet. Transferring is effectively irreversible: the environments leave the source project for good, and replacing them isn't self-serve. Before the transfer runs, the dashboard shows a review step that lists the environments being moved (grouped into staging and production) and requires you to acknowledge the implications. Environments can only be transferred into a **new** project at creation time. Transferring into an existing project isn't supported yet.  ## Frequently asked questions ### Do projects cost extra? No. Projects are an organizational layer in the dashboard. Billing still applies per environment based on usage — see [pricing](https://workos.com/pricing) for details. ### Can I move an environment to a different project? Today, environments can only be moved into a **new** project when you create it. See [transfer environments from another project](#transfer-environments-from-another-project). Transferring into an existing project isn't supported yet. A transfer is also blocked when the source project has [project-level configuration](#project-level-configuration), such as feature flags, that can't yet be copied to the new project. ### How do projects relate to organizations? They're unrelated. A project is a dashboard-level grouping of environments that you manage as a developer. An [organization](https://workos.com/docs/reference/organization) is an in-app, multi-tenant concept that represents one of your customers and the users within it.