Deploy to production

Before you begin:

1. You will need to have a domain you own.
2. You will need to be able to add DNS records on your domain.
3. You will need social sign-in (OAuth) credentials for any providers that you would like to use in production. Each OAuth provider has a dedicated guide on how to set up OAuth credentials for Clerk production apps.

Create your production instance

1. Navigate to the Clerk Dashboard.
2. At the top of the Dashboard, select the Development button to reveal the instance selection dropdown. Select Create production instance.
3. You will be prompted with a modal to either clone your development instance settings to your production instance or create your production instance with Clerk's default settings.
4. The homepage of the dashboard will show you what is still required to deploy your production instance.

Update your publishable key

A common mistake when deploying to production is forgetting to change your publishable key to your production instance's key. The best way to handle this is to use environment variables or build-time configuration so the correct key is set for each environment.

Your publishable key is formatted as pk_test_ in development and pk_live_ in production. Pass it to ClerkAuth during initialization:

ClerkAuth(
  config: ClerkAuthConfig(
    publishableKey: const String.fromEnvironment('CLERK_PUBLISHABLE_KEY'),
  ),
  child: MaterialApp(...),
)

Run your Flutter app with the production key:

flutter run --dart-define=CLERK_PUBLISHABLE_KEY=pk_live_...

Or use a configuration file:

flutter run --dart-define-from-file=config.production.json

OAuth credentials

In development, for most social providers, Clerk provides you with a set of shared OAuth credentials.

In production, these are not secure and you will need to provide your own. Each OAuth provider has a dedicated guide on how to set up OAuth credentials for Clerk production apps.

DNS records

Clerk uses DNS records to provide session management and emails verified from your domain.

To see what DNS records you need, navigate to the Domains page in the Clerk Dashboard.

Confirm your iOS app is registered in production

Ensure your iOS app exists in the production instance under Native Applications. You will need your App ID Prefix and Bundle ID.

Update associated domains

In Xcode, update Associated Domains to use your production Frontend API URL.

Under Signing & Capabilities, add or update the entry to webcredentials:{YOUR_FRONTEND_API_URL}.

Confirm your Android app is registered in production

Ensure your Android app exists in the production instance under Native Applications. You will need your Package Name and SHA-256 certificate fingerprint.

Configure allowlisted redirect URLs

Clerk ensures that security critical nonces are passed only to allowlisted URLs when the SSO flow is completed in native browsers or webviews. For maximum security in your production instances, you need to allowlist your custom redirect URLs via the Clerk Dashboard or the Clerk Backend API.

To allowlist a redirect URL via the Clerk Dashboard:

1. In the Clerk Dashboard, navigate to the Native applications page.
2. Scroll down to the Allowlist for mobile SSO redirect section and add your redirect URLs.

Deploy certificates

The Clerk Dashboard home page will tell you what steps are still required to deploy your production instance. Once you have completed all of the necessary steps, a Deploy certificates button will appear. Selecting this button will deploy your production instance.

Test on a physical device

Build a release/TestFlight build with production keys and verify behavior.

Build a signed release APK or use Play Store internal testing with production keys and verify behavior.

Troubleshooting

DNS records not propagating with Cloudflare

Clerk uses a DNS check to validate this CNAME record. If this subdomain is reverse proxied behind a service that points to generic hostnames, such as Cloudflare, the DNS check will fail. Set the DNS record for this subdomain to a "DNS only" mode on your host to prevent proxying.

Deployment stuck in certificate issuance

If your instance is stuck during TLS certificate issuance for longer than a few minutes, this might be caused due to certain CAA DNS records set on your primary domain.

CAA are DNS records you may set to denote which certificate authorities (CA) are permitted to issue certificates for your domain, as a security measure against certain attacks. When you deploy your application, Clerk attempts to provision certificates using either the LetsEncrypt or Google Trust Services certificate authorities.

Ensure that your primary domain (e.g., example.com) does not have any CAA records that prevent either LetsEncrypt or Google Trust Services from issuing certificates for your domain. To check this, run the following command in your terminal, replacing example.com with your app’s domain:

dig example.com +short CAA

If the command returns an empty response, your domain is correctly configured. If it returns any text, you need to remove the CAA records from your primary domain to avoid potential downtime during certificate renewal.

Incorrect domain

If you accidentally set the wrong domain, you can change it through the Clerk Dashboard or the Backend API. For more information, see the dedicated guide.