Leap recommends using Clerk for user authentication, it’s a scalable and enterprise-ready authentication solution that comes with a generous free tier. Most of the integration can be handled inside Leap, but there are a couple of manual setup steps to be aware of.

​
Step by step

1. Prompt Leap In the chat box, paste: 
Implement authentication using Clerk. Store the secret key using secrets and the publishable key as an environment variable in config.ts.
Leap will now implement the auth flow using Clerk’s SDK and tell you what it needs next. 2. Create a Clerk account and app
  • Go to clerk.com, create an account, then create an application in the Clerk dashboard.
  • Copy your Publishable key and Secret key. You will use both.
3. Add the publishable key to your app
  • In the Leap code viewer, use search to look for where to configure your publishablekey, it’s usually found in frontend/config.ts.
  • Paste the Publishable key you copied from the Clerk dashboard in the location Leap indicates for your stack.
  • Typical variable names include clerkPublishableKey or similar. Follow what Leap generated.
Publishable key 4. Store the secret key as a Leap secret
  • When prompted by Leap (blue message in the left chat), store the Secret key using Leap’s secrets manager.
  • Or if you don’t see a blue message, find it manually: Infrastructure → Secrets, find a secret such as ClerkSecretKey, paste your Clerk Secret key, then save.
  • If you don’t see any secret in the Infrastructure page, prompt Leap again to use Secrets to store the Clerk Secret Key.
Secret key 5. Verify the code that Leap generated Authentication is an important part of your application. We recommend always spending some time verifying that Leap’s implementation is correct. Ask a developer colleague or friend if you need help.
  • Leap usually adds provider or middleware setup in your app entry point and server handlers.
  • You can ask Leap to point you to files to review, open them and confirm:
    • A top-level provider or wrapper for Clerk on the client.
    • Server routes or middleware that verify the session using the secret key.
    • Example protected routes that check for a signed-in user.
6. Run the app and preview
  • Use the Preview inside Leap to test your app.
  • If Clerk blocks the Leap iframe (see Known issues below), click Open preview in separate tab and use the app there.
7. Test the full auth flow
  • In the running app, click Sign up or Sign in and complete the flow.
  • Visit a protected page to confirm redirect and access rules.
  • If your server reads session claims, trigger a request and check the logs or UI that the user ID is present.
8. Deploy readiness checklist
  • Before deploying to a cloud environment, ensure you have saved the secret key. Encore Cloud will not deploy unless all secrets have been set, in order to avoid production bugs.
  • In the Clerk dashboard, add your production domain to allowed origins if needed.

​
Known issues and workarounds

Iframe security blocking Clerk’s security policies may block Leap’s preview iframe from displaying your application. This will trigger an error like: Content security policy error If you see this, simply open your preview app in a separate browser tab.

​
Getting help

If you need assistance, join our Discord and we will help you get unblocked.