Staging vs. production environments

WorkOS provides two separate environments – staging and production – so you can build and test your integration before going live. This guide explains the differences between them, when to use each, and how to transition from staging to production.

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 don’t carry over between them.

One notable exception is AuthKit branding. Logo, colors, and custom theme settings are shared across environments, so any branding you configure in Branding will appear in both staging and production.

Use the staging environment when you’re:

• Evaluating WorkOS for the first time and exploring the API
• Building your integration locally or in a development environment
• Testing Single Sign-On, 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.

Use the production environment when you’re:

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

Production requires adding billing information in the WorkOS Dashboard. Enterprise connections (such as SAML-based Single Sign-On or SCIM-based Directory Sync) in production incur per-connection charges. AuthKit is free for up to 1 million monthly active users (MAUs), after which usage-based pricing applies. OAuth connections and all staging connections are free.

Staging and production are separate environments. Apart from branding, nothing carries over automatically. When you switch to production, you’ll need to set up the following:

• API keys and Client IDs – see API authentication
• Redirect URIs – see Redirect URI requirements
• Organizations and connections – if you’re using SSO or Directory Sync
• Webhook endpoints and secrets – if your integration consumes WorkOS events; see Webhooks
• Custom domains – if you want to use them in production; see Custom domains

Every integration should do the following:

1. Verify your integration works end-to-end in staging. For most workflows, staging is sufficient to fully validate your integration before touching production.
2. Unlock production by adding billing information in the WorkOS Dashboard.
3. Generate your production API key and store it securely. Production API keys can only be viewed once. See API authentication.
4. Note your production Client ID and update your app’s environment variables.
5. Configure production redirect URIs. For most web apps these must use https://. See Redirect URI requirements.
6. (Optional) Set up custom domains for AuthKit, Admin Portal, or the Authentication API.
7. Test the full authentication flow in production before sending real traffic there.

If you’re using enterprise features like SSO or Directory Sync, you’ll also need to:

1. Recreate organizations and connections in production for your live customers.
2. Set up production webhook endpoints and store the new signing secret if your integration consumes WorkOS events. See Webhooks.
3. Generate Admin Portal links for customer IT admins to self-configure their connections if you’re using self-serve setup.

For the full Single Sign-On 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. Every workspace starts with a staging and production environment, but you can add more. Additional environment creation may be available directly in your dashboard settings. If you don’t see the option, contact support to have one created.

Can I copy data from staging to production?

Not currently. Staging and production are fully isolated, and there isn’t a built-in way to promote or migrate organizations, connections, or users between them today. When you’re ready to go live, you’ll need to recreate your organizations and connections in the production environment. Your end users will re-authenticate through AuthKit, which creates their accounts in production automatically.

Can I convert a staging environment to a production environment?

Not self-serve. If you’ve accidentally been serving live traffic from a staging environment, contact support for assistance. To avoid this situation, keep staging for development and testing only – staging environments are not intended for customer-facing traffic per the Terms of Service.

What features are only available in production?

Almost everything works identically across both environments. The main differences are:

• Custom domains for AuthKit, Admin Portal, and the Authentication API are only available in production environments.
• SSO and Directory Sync connections in staging are not billed, so you can test freely.

Is it safe to use real OAuth credentials in staging?

Yes. You can safely configure real OAuth provider credentials (Google, Microsoft, GitHub, etc.) in your staging environment for testing. Staging environments are fully functional and secure – the only limitations are the production-only features listed above.

Can I move an environment between workspaces?

No. Environments are tied to a specific workspace and can’t be transferred.