Projects
Group related environments under a project, and learn when to use projects, environments, and applications.
A project is a dashboard-level grouping of environments. Every WorkOS team is organized as a hierarchy:
Every team starts with a single project that contains a staging and a production environment. Projects let you keep more than one of these setups under a single WorkOS team, each with its own environments and project-level configuration.
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 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 within a single environment.
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.
- Need somewhere isolated to develop and test before going live? Add an environment.
- Need a fully separate setup – its own configuration and staging and production environments – under one team? Create a project.
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:
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.
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.
Create a project from the WorkOS Dashboard. 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.
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.
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 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.
Do projects cost extra?
No. Projects are an organizational layer in the dashboard. Billing still applies per environment based on usage – see 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. Transferring into an existing project isn’t supported yet. A transfer is also blocked when the source project has 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 is an in-app, multi-tenant concept that represents one of your customers and the users within it.