Staging vs. production environments

Every WorkOS workspace includes a staging environment and a production environment. These are fully separate: API keys, organizations, connections, users, and webhook endpoints are all scoped to a single environment and do not carry over between them.

The one exception is AuthKit branding. Logo, colors, and custom theme settings are shared across environments, so any branding configuration will appear in both staging and production.

Use the staging environment when you are:

• Evaluating WorkOS for the first time and exploring the API
• Building your integration locally or in a development environment
• Testing SSO, Directory Sync, or other enterprise features using the built-in test identity provider (IdP)
• Running automated tests or CI pipelines against WorkOS
• Demoing your integration to internal stakeholders before launch

Staging is free. No connections in staging incur charges, regardless of type. There is no limit to the number of organizations you can create.

Use the production environment when you are:

• Serving real end users who need to authenticate or connect via SSO
• Onboarding enterprise customers with live identity provider connections
• Deploying to a customer-facing URL with HTTPS

Production requires adding billing information to the WorkOS dashboard. Only enterprise connections (such as SAML-based Single Sign-On or SCIM-based Directory Sync) in production incur charges. OAuth connections and all staging connections are free.

No. Staging and production are fully separate environments. Nothing carries over automatically. When you are ready to go live, you will need to:

1. Unlock production by adding billing information in the WorkOS dashboard.
2. Generate a production API key (remember, you can only view it once).
3. Note your production Client ID.
4. Update your environment variables to use the production API key and Client ID.
5. Configure production redirect URIs (must use https://).
6. Set up production webhooks with a new endpoint and signing secret.
7. Recreate organizations and connections in production for your live customers.

Branding is the only configuration that carries over. Everything else – organizations, connections, redirect URIs, API keys, webhook endpoints – must be set up fresh.

Staging is designed for development and testing, not for serving production traffic. Key details:

• Rate limits are the same as production (see the rate limits documentation for details).
• No organization limits – you can create as many organizations as you need.
• Storage and usage are intended for testing volumes, not production-scale traffic.
• Product setup thresholds may differ slightly – for example, SSO in staging requires 2 connections to unlock (because a seeded test IdP is included), while production requires 1.

For most development and testing workflows, staging has no practical limitations.

If you configure a test SAML provider in production, be aware that:

• Test providers are meant for development – they may display generic or placeholder company names to your users.
• Any connections configured in production (even test ones) may count toward billing if they are enterprise connection types.
• Do all testing in staging and only set up real customer connections in production.

Some developers prefer to skip staging and build directly against production, especially for simple use cases like AuthKit username/password authentication. Here are the tradeoffs:

Pros:

• Fewer environment variables to manage
• No migration step when you go live
• What you test is exactly what ships

Cons:

• Requires adding billing information upfront, even if you are just evaluating
• Production API keys are view-once, so you must store them securely from the start
• Redirect URIs must use https://, which adds setup overhead for local development
• Mistakes during development could affect live users if you later add real customers to the same environment
• No built-in test identity provider – you would need a real IdP connection to test SSO

Recommendation: Use staging for development and testing, then transition to production when you are ready to onboard real customers. The migration is straightforward – it mainly involves swapping environment variables and recreating your configuration.

When you are ready to move from staging to production:

For the full SSO launch checklist, see the SSO launch checklist.

Do I need a separate WorkOS account for staging and production?

No. Both environments are included in a single WorkOS workspace.

Can I have multiple staging or production environments?

Yes. WorkOS can create additional environments for your workspace. Contact support if you need more than the default staging and production environments.

Is there a way to avoid the billing requirement for production?

Currently, production requires billing information to unlock. However, you will not be charged unless you have active enterprise connections. For simple AuthKit usage without SSO, there is no cost beyond adding billing info.

Can I move an environment between workspaces?

No. Environments are tied to a specific workspace and cannot be transferred.