> ## Documentation Index
> Fetch the complete documentation index at: https://blueprint.codeandcreed.tech/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> Authenticate your users with Clerk

<Warning>
  **DO NOT upgrade any Clerk dependencies** unless you're following their official migration guide and understand the breaking changes. Upgrading without proper migration can break your authentication flow, webhooks, and user management. The current Clerk version in the boilerplate is tested and stable.
</Warning>

This guide covers working with Clerk for authentication in Titan.

Titan already comes with a working webhook handler for Clerk authentication events that synchronizes user data with your database. See `app/api/auth/webhook.ts` for the implementation.

When a user signs up or updates their profile in Clerk, the webhook will trigger and update your database accordingly, ensuring your user data stays in sync.

We need to make sure we create these webhooks in Clerk (both for testing locally and in production)

## Testing authentication locally

<Note>
  Assuming you have the ngrok url running, you can test the authentication flow locally.
</Note>

1. Set `config.auth.enabled` to `true` in `config.ts`

2. **Create a webhook in Clerk**

a. Go to `Configure` -> `Webhooks` -> `+ Add Endpoint`

b. Set the `Endpoint URL` to `[your-ngrok-url]/api/auth/webhook`

c. Set the `Events` to `user.created` and `user.updated`

3. **Run your app**

```bash theme={null}
bun run dev
```

4. **Test the authentication flow**

When you successfully sign up with Clerk in your app, you should now successfully see the User added to your Clerk dashboard (Under the `Users` tab) and a new record created in your `users` table in Supabase ✅

## Configuring authentication in production

You will need to create a new webhook in Clerk AND configure your production environment with the appropriate API keys.

1. **Create a Production Instance of your Clerk Application**

   a. In your Clerk dashboard, create a new production application or switch your existing application to production mode

   b. Copy your Production API Keys:

   * `NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY`
   * `CLERK_SECRET_KEY`

   c. Setup the production webhook:

   * Go to `Configure` -> `Webhooks` -> `+ Add Endpoint`
   * Set the `Endpoint URL` to `https://[your-production-domain]/api/auth/webhook`
   * Set the `Events` to `user.created` and `user.updated`
   * Copy the webhook secret for your environment variables

   <Note>
     You can use vercel's default domain if you haven't bought a custom domain yet.
   </Note>

   d. Configure Google Auth for your production application

   e. Connect your custom domain in the Clerk dashboard

2. **Update Environment Variables**

   Ensure these environment variables are set in your production environment (e.g., Vercel):

   ```txt theme={null}
   CLERK_SECRET_KEY="Your production secret key"
   NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY="Your production publishable key"
   CLERK_WEBHOOK_SECRET="Your production webhook secret"
   ```

3. **Deploy Your Application**

Update your production environment variables in Vercel to use your production Clerk keys and deploy your application.

## Common Issues & Troubleshooting

<Warning>
  To be updated soon...
</Warning>