Instances / Environments

When creating a new application within Clerk, you are provided with two instances: Development and Production. These instances vary slightly and should only be used appropriately.

Development instance

A Development instance is Clerk's default instance type and has characteristics that allow it to be more useful for local development. To facilitate development and local authentication, Development instances have a more relaxed security posture and are not suitable for production workloads.

Some notable examples of Development-only characteristics in a Clerk application are:

• A Development banner is shown prominently in the Clerk Dashboard to make clear you're managing or configuring non-production data
• Email and SMS templates are prefixed with the environment type to prevent against using Development instances for production purposes
• Some social connections use shared credentials by default
• The Account Portal will use a Clerk development domain that ends with accounts.dev instead of your app's production domain
• OAuth consent screens will show the development domain that ends with accounts.dev instead of your production domain
• Search engines will not be able to crawl and index your application
• Development instances are capped at 100 users, and user data can not be transferred between instances
• The architecture of Clerk's sessions management is different in development environments compared to production environments, due to the need to communicate cross-domain between localhost and <slug>.accounts.dev. The __clerk_db_jwt object is only used in development environments. For more specific details on the differences between Clerk's session management architecture in development and production environments, see the technical breakdown below.

Production instance

A Production instance is the more robust option of Clerk's instance types. Production instances are meant to support high volumes of traffic and by default, have a more strict security posture.

Some notable differences between Production and Development instances in a Clerk application are:

• You must associate a production domain within the Clerk Dashboard
• You are required to provision your own SSO credentials

When deploying to production, you must first activate your Production environment. See the Deploying to Production guide to learn about the process and avoid common pitfalls.

Staging environments

Clerk does not currently support staging instances in Clerk applications. However, you can set up a "staging environment" by creating a separate Clerk application with a separate domain. For more information, see the staging guide.

Preview environments

See the preview environment guide to learn how to use Clerk with your preview deployments.

Session architecture differences

Clerk manages session state differently in production and development environments.

In production, Clerk uses a client token to represent the user's session. This client token is stored as an HttpOnly cookie (__client) on the Clerk FAPI domain. Because, in production, FAPI is hosted on a subdomain of your application (e.g., clerk.example.com) via a CNAME record, your app's frontend and FAPI are on the same site. This allows the client token to be securely and reliably sent with each request from your frontend to FAPI using same-site cookies.

However, in development, your app's frontend typically runs on a localhost domain, while FAPI for development instances is hosted on a domain ending with accounts.dev. As a result, requests from your app's frontend to FAPI are cross-site, and the client token cannot be securely and reliably stored or transmitted using cookies.

To address these limitations, development instances use a different approach to maintain session state. An object called the "dev browser", which is linked directly to the client token within Clerk's internals, is used to maintain session state across the session lifetime, and is transmitted via querystring (__clerk_db_jwt) rather than via cookie. This strategy allows for a more reliable experience for local development, as it does not require the use of cross-site cookies.

While this enables smooth local development workflows, it is not secure enough for production use. Including a sensitive value like the client token in a querystring is not a strong security practice, as it can be seen directly in server logs, browser history, internet providers' logs, and could be potentially intercepted by third-parties via malicious browser extensions or network interceptors. This is why the __clerk_db_jwt object is not used in production instances and the same-site cookie (__client) is used instead.