Projects
Group related environments under a project, and learn when to use projects, environments, and multiple applications.
A project is a dashboard-level grouping of environments. Every WorkOS account is organized as a hierarchy:
Every account 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 account, 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 account. 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.
- Independent billing and go-live timelines for each product.
If you only need an isolated stage for development and testing, 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 multiple applications within a single environment.
These three concepts solve different problems. The table below summarizes how they differ.
| Concern | Multiple applications | Environments | Projects |
|---|---|---|---|
| Scope | Clients within one environment | Stages within one project | Groups of environments |
| User pool | Shared across applications | Isolated per environment | Isolated per environment |
| API keys, connections | Per application | Per environment | Per environment |
| Project-level config | Shared | Shared within a project | Separate per project |
| Typical use | Web, mobile, and desktop clients of one product | Staging vs. production | Separate products or business units |
When deciding which to reach for:
- Need separate sign-in surfaces that share one user pool? Use multiple applications.
- Need an isolated stage to develop and test against before going live? Add an environment.
- Need a fully separate setup – its own configuration and staging and production environments – under one account? 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:
- Feature flags
- Tags
- Audit Logs schema
- Custom email domains
Because these settings live at the project level, they determine whether an environment can be moved to a different project. An environment that relies on project-level configuration can’t be transferred until that configuration is accounted for in the destination project.
By default, branding is configured per environment, so each environment can have its own logo, colors, and theme. If you’d prefer to share a single branding configuration across all environments in a project, contact support.
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?
Environments can be grouped into projects, but an environment that depends on project-level configuration – such as feature flags – can’t be moved until that configuration is reconciled with the destination project. See project-level configuration.
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.