Skip to main content
Docs

Using production keys in local development

Caution

This approach is strongly discouraged and not officially supported. Only use it when you need to debug production-specific issues that can't be reproduced in a development environment.

In rare cases, you may need to debug issues that only occur in your production environment. This guide explains how to configure your local development environment to use production Clerk keys.

Prerequisites

Why this works

Clerk enforces origin validation in production to protect your users. Production keys (pk_live_ and sk_live_) only work with your configured production domain. This means localhost won't work with production keys. You'll see an error like:

Clerk: Production Keys are only allowed for domain "your-domain.com".

However, authentication across subdomains works by default in Clerk production instances. By mapping a subdomain of your production domain to your local machine, you can use production keys locally.

Warning

This works for troubleshooting many situations, but there are some limitations:

  • OAuth won't work - Social sign-in providers (Google, GitHub, etc.) have their own redirect URL restrictions. Your local subdomain won't be in their allowed list unless you add it to each provider's configuration.
  • Webhooks won't reach localhost - Clerk webhooks can't reach your local machine. Use a tool like Pinggy or ngrok if you need to test webhooks.
  • Session behavior differs - Production and development instances have different session architectures. Some issues may still not reproduce locally.

Map a subdomain to localhost

Configure your machine to resolve a subdomain of your production domain to 127.0.0.1 by editing your hosts file.

Replace your-domain.com with your actual production domain. Changes take effect immediately, no restart required.

Run the following command in Terminal:

terminal
echo "127.0.0.1 local.your-domain.com" | sudo tee -a /etc/hosts

Enter your password if prompted. The line will be added to your hosts file.

  1. Search for Notepad in the Start menu.
  2. Right-click and select Run as administrator.
  3. In Notepad, select File > Open and navigate to C:\Windows\System32\drivers\etc\hosts. You may need to change the file filter from "Text Documents" to "All Files" to see it.
  4. Add the following line at the end of the file:
    hosts
    127.0.0.1 local.your-domain.com
  5. Save the file.
  1. Open the hosts file in your preferred text editor with elevated privileges:
    terminal
    sudo nano /etc/hosts
  2. Add the following line at the end of the file:
    /etc/hosts
    127.0.0.1 local.your-domain.com
  3. Save and exit (in nano, press Ctrl+O to save, then Ctrl+X to exit).

Configure environment variables

Update your .env file to use your production Clerk keys. Production keys start with pk_live_ and sk_live_ instead of pk_test_ and sk_test_.

.env
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_live_xxxxx
CLERK_SECRET_KEY=sk_live_xxxxx

Replace pk_live_xxxxx and sk_live_xxxxx with your actual production keys from the API keys page in the Clerk Dashboard.

Run your server with HTTPS on port 443

Important

You must run your server on port 443 (the standard HTTPS port). When browsers send requests from non-standard ports like 3000, they include the port in the Origin header (e.g., https://local.your-domain.com:3000). Clerk's origin validation fails when the port is included.

Production Clerk requires HTTPS on port 443. Running on port 443 requires elevated privileges on most systems.

Next.js 13.5+ can automatically generate a locally-trusted certificate. You'll also need to configure Next.js to allow requests from your subdomain.

Add the following to your Next.js configuration:

next.config.js
const nextConfig = {
  allowedDevOrigins: ['local.your-domain.com'],
  // Other options...
}

export default nextConfig

Then start your server on port 443:

terminal
sudo npx next dev --experimental-https -p 443

Note

The --experimental-https flag generates a certificate for localhost, not your subdomain. Your browser will show a certificate warning when accessing the subdomain. You can safely proceed past this warning for local debugging, or use mkcert to generate a proper certificate.

Use mkcert to create locally-trusted certificates that match your subdomain:

terminal
# Install mkcert (macOS)
brew install mkcert

# Create a local CA and install it in the system trust store
mkcert -install

# Generate certificates for your subdomain
mkcert local.your-domain.com

This creates local.your-domain.com.pem and local.your-domain.com-key.pem files. Configure your development server to use these certificates and run on port 443. The exact configuration depends on your framework.

Test the configuration

  1. Open your browser and navigate to your local subdomain: https://local.your-domain.com
  2. If you see a certificate warning, select Advanced and proceed to the site.
  3. Verify that Clerk loads and you can sign in.

If you navigate to https://localhost instead, you should see the origin validation error, which confirms that production keys are correctly restricted.

Clean up

After debugging:

  1. Revert your .env file to use development keys (pk_test_xxxxx and sk_test_xxxxx).
  2. Remove the allowedDevOrigins configuration from next.config.js (if applicable).
  3. Remove the entry from your hosts file:

Run the following command in Terminal, replacing your-domain.com with your actual production domain:

terminal
sudo sed -i '' '/local\.your-domain\.com/d' /etc/hosts

Enter your password if prompted. The line will be removed from your hosts file.

  1. Search for Notepad in the Start menu. 1. Right-click and select Run as administrator.
  2. In Notepad, select File > Open and navigate to C:\Windows\System32\drivers\etc\hosts.
  3. Delete the line containing local.your-domain.com. 1. Save the file.

Run the following command, replacing your-domain.com with your actual production domain:

terminal
sudo sed -i '/local\.your-domain\.com/d' /etc/hosts

Feedback

What did you think of this content?

Last updated on

GitHubEdit on GitHub