Proxying the Clerk Frontend API
Clerk supports two configuration methods for connecting to the Clerk Frontend API: CNAME and Proxy.
The recommended way to connect to the Clerk Frontend API is to set up CNAME records and use DNS. However, if you're unable to use this approach, or would like more control over your integration with Clerk, you can use a proxy.
When using a proxy, all requests to the Frontend API will be made through your domain. This allows you to use your own SSL certificate, and gives you more control over how you configure your application.
How to use proxying
Create your application and install Clerk
To get started, you need to create an application from the Clerk Dashboard. Once you create an instance via the Clerk Dashboard, you will be prompted to choose a domain. For the purposes of this guide, the domain will be app.dev
.
Configure your proxy server
For this example, /__clerk
is used as the path for the proxy. Your proxy server must be on the same domain as your application.
You can choose any path you'd like, but it must be unique and not conflict with any other routes in your application.
Requirements
Requests to https://app.dev/__clerk/*
must be forwarded to https://frontend-api.clerk.dev/*
with the body and all headers intact.
Three additional headers must be set
Clerk-Proxy-Url
: Needs to have the full proxy URL.Clerk-Secret-Key
: The Secret Key for your Clerk instance.X-Forwarded-For
: The IP address of the original client making the request.
Example configuration
http {
# ...
server {
# ...
location /__clerk/ {
rewrite ^/__clerk/(.*)$ /$1 break;
proxy_pass https://frontend-api.clerk.dev;
proxy_set_header Clerk-Proxy-Url https://app.dev/__clerk;
proxy_set_header Clerk-Secret-Key sk_live_***;
proxy_set_header X-Forwarded-For $remote_addr;
proxy_redirect off;
}
}
}
Enable proxying
In order to enable proxying, you need to set a proxy URL for your Clerk instance's domain. This can be done through the Clerk Dashboard or through the Backend API.
- In the Clerk Dashboard, navigate to the Domains page.
- In the Frontend API section, select the Advanced dropdown.
- In the Proxy URL field, enter your proxy URL. The proxy URL must be a valid URL and resolve correctly.
Configure your proxy setup
You can configure your proxy setup by either:
- Setting environment variables
- Using properties in your application
Environment variables
To configure your proxy setup using environment variables, your .env
file should look like this:
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=YOUR_PUBLISHABLE_KEY
CLERK_SECRET_KEY=YOUR_SECRET_KEY
NEXT_PUBLIC_CLERK_PROXY_URL=https://app.dev/__clerk
To configure your proxy setup using properties in your Next.js application, set the proxyUrl
property on the <ClerkProvider>
component.
import { ClerkProvider } from '@clerk/nextjs'
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
<ClerkProvider proxyUrl="https://app.dev/__clerk">
<html lang="en">
<body>{children}</body>
</html>
</ClerkProvider>
)
}
Ready to go 🎉
Your application should now be able to access the Frontend API from your proxy!
If you have any questions about proxying, or you're having any trouble setting this up, contact .
Feedback
Last updated on