# Clerk Kimlik Doğrulama Kurulum Rehberi

## 📋 Genel Bakış

LetsGoCappadocia uygulaması, kullanıcı kimlik doğrulama için Clerk.com kullanmaktadır. Bu rehber, Clerk API anahtarlarını nasıl alacağınızı ve yapılandıracağınızı adım adım açıklar.

---

## 🔑 Gerekli API Anahtarları

### 1. **VITE_CLERK_PUBLISHABLE_KEY** (Frontend)
- **Açıklama:** Frontend uygulamasında kullanıcı kimlik doğrulama için gerekli
- **Format:** `pk_test_...` veya `pk_live_...` ile başlar
- **Kullanım Yeri:** React uygulaması (.env dosyası)
- **Güvenlik:** Public key - tarayıcıda görünür olabilir

### 2. **CLERK_SECRET_KEY** (Backend)
- **Açıklama:** Backend webhook doğrulama ve admin işlemleri için gerekli
- **Format:** `sk_test_...` veya `sk_live_...` ile başlar
- **Kullanım Yeri:** Supabase Edge Functions
- **Güvenlik:** ⚠️ GİZLİ - Asla frontend'de kullanmayın!

### 3. **CLERK_WEBHOOK_SECRET** (Webhook)
- **Açıklama:** Clerk webhook'larını doğrulamak için gerekli
- **Format:** `whsec_...` ile başlar
- **Kullanım Yeri:** Supabase Edge Functions (clerk-webhook)
- **Güvenlik:** ⚠️ GİZLİ - Webhook güvenliği için kritik

---

## 📝 Adım Adım Kurulum

### Adım 1: Clerk Hesabı Oluşturma

1. **Clerk.com'a gidin:** https://clerk.com/
2. **Sign Up** butonuna tıklayın
3. E-posta adresinizle kayıt olun
4. E-posta doğrulamasını tamamlayın

### Adım 2: Yeni Uygulama Oluşturma

1. Clerk Dashboard'a giriş yapın
2. **"Create Application"** butonuna tıklayın
3. Uygulama adını girin: `LetsGoCappadocia`
4. Kimlik doğrulama yöntemlerini seçin:
   - ✅ Email
   - ✅ Google (opsiyonel)
   - ✅ Phone (opsiyonel)
5. **Create Application** butonuna tıklayın

### Adım 3: API Anahtarlarını Alma

#### 3.1 Publishable Key ve Secret Key

1. Clerk Dashboard'da sol menüden **"API Keys"** seçeneğine tıklayın
2. **Publishable Key** bölümünü bulun:
   - `pk_test_...` ile başlayan anahtarı kopyalayın
   - Bu anahtarı `VITE_CLERK_PUBLISHABLE_KEY` olarak kaydedin

3. **Secret Keys** bölümünü bulun:
   - `sk_test_...` ile başlayan anahtarı kopyalayın
   - ⚠️ **"Show"** butonuna tıklayarak anahtarı görünür hale getirin
   - Bu anahtarı `CLERK_SECRET_KEY` olarak kaydedin

#### 3.2 Webhook Secret

1. Clerk Dashboard'da sol menüden **"Webhooks"** seçeneğine tıklayın
2. **"Add Endpoint"** butonuna tıklayın
3. Webhook URL'ini girin:
   ```
   https://vtztatcglebrnvikvntf.supabase.co/functions/v1/clerk-webhook
   ```
4. **Events** bölümünde şu olayları seçin:
   - ✅ `user.created`
   - ✅ `user.updated`
   - ✅ `user.deleted`
5. **Create** butonuna tıklayın
6. Oluşturulan webhook'un detay sayfasında **"Signing Secret"** bölümünü bulun
7. `whsec_...` ile başlayan anahtarı kopyalayın
8. Bu anahtarı `CLERK_WEBHOOK_SECRET` olarak kaydedin

---

## 🔧 Anahtarları Yapılandırma

### Yöntem 1: .env Dosyası (Önerilen - Development)

1. Proje kök dizinindeki `.env` dosyasını açın
2. Aşağıdaki satırları ekleyin:

```bash
# Clerk Authentication
VITE_CLERK_PUBLISHABLE_KEY=pk_test_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
```

3. Dosyayı kaydedin
4. Development server'ı yeniden başlatın:
```bash
npm run dev
```

### Yöntem 2: Admin Panel (Önerilen - Production)

1. Uygulamaya admin olarak giriş yapın
2. **Admin Panel > Settings** sayfasına gidin
3. **"API Keys Management"** bölümünü bulun
4. **"Add New Key"** butonuna tıklayın
5. Her anahtar için:
   - **Key Name:** `VITE_CLERK_PUBLISHABLE_KEY`
   - **Key Value:** Kopyaladığınız publishable key
   - **Save** butonuna tıklayın

### Yöntem 3: Supabase Secrets (Backend Anahtarları)

Backend anahtarları (CLERK_SECRET_KEY, CLERK_WEBHOOK_SECRET) Supabase Edge Functions için yapılandırılmalıdır:

1. Supabase Dashboard'a gidin: https://supabase.com/dashboard
2. Projenizi seçin: `vtztatcglebrnvikvntf`
3. Sol menüden **"Edge Functions"** seçeneğine tıklayın
4. **"Manage secrets"** butonuna tıklayın
5. Her secret için:
   - **Name:** `CLERK_SECRET_KEY`
   - **Value:** Kopyaladığınız secret key
   - **Add** butonuna tıklayın
6. Aynı işlemi `CLERK_WEBHOOK_SECRET` için tekrarlayın

---

## ✅ Doğrulama

### Frontend Doğrulama

1. Uygulamayı açın: http://localhost:5173
2. **Sign In** veya **Sign Up** sayfasına gidin
3. Clerk login formu görünüyorsa ✅ başarılı
4. Eğer hata mesajı görüyorsanız:
   - Browser console'u açın (F12)
   - Hata mesajlarını kontrol edin
   - `VITE_CLERK_PUBLISHABLE_KEY` doğru mu kontrol edin

### Backend Doğrulama

1. Admin Panel'e giriş yapın
2. **Admin Panel > Clerk Diagnostics** sayfasına gidin
3. **"Test Clerk Connection"** butonuna tıklayın
4. Başarılı mesajı görüyorsanız ✅ backend doğru yapılandırılmış

### Webhook Doğrulama

1. Clerk Dashboard > Webhooks sayfasına gidin
2. Oluşturduğunuz webhook'u seçin
3. **"Send test event"** butonuna tıklayın
4. `user.created` event'ini seçin
5. **Send** butonuna tıklayın
6. Response `200 OK` ise ✅ webhook çalışıyor

---

## 🔒 Güvenlik En İyi Uygulamaları

### ✅ Yapılması Gerekenler

1. **Secret Key'leri Asla Paylaşmayın**
   - GitHub, Slack, email gibi platformlarda paylaşmayın
   - Screenshot alırken anahtarları gizleyin

2. **Environment Variables Kullanın**
   - Anahtarları kod içine hard-code etmeyin
   - `.env` dosyasını `.gitignore`'a ekleyin

3. **Development ve Production Anahtarlarını Ayırın**
   - Test için `pk_test_...` ve `sk_test_...` kullanın
   - Production için `pk_live_...` ve `sk_live_...` kullanın

4. **Anahtarları Düzenli Olarak Rotate Edin**
   - Her 3-6 ayda bir anahtarları yenileyin
   - Şüpheli aktivite durumunda hemen yenileyin

5. **Webhook Secret'ı Koruyun**
   - Webhook endpoint'inizi public yapmayın
   - Sadece Clerk IP'lerinden gelen istekleri kabul edin

### ❌ Yapılmaması Gerekenler

1. **Frontend'de Secret Key Kullanmayın**
   - `CLERK_SECRET_KEY` sadece backend'de kullanılmalı
   - Browser'da görünür olmamalı

2. **Anahtarları Git'e Commit Etmeyin**
   - `.env` dosyasını commit etmeyin
   - `.env.example` kullanın (değerler olmadan)

3. **Public Repository'lerde Anahtarları Paylaşmayın**
   - GitHub, GitLab gibi platformlarda anahtarları expose etmeyin

---

## 🐛 Sorun Giderme

### Hata: "Clerk Publishable Key bulunamadı"

**Çözüm:**
1. `.env` dosyasında `VITE_CLERK_PUBLISHABLE_KEY` tanımlı mı kontrol edin
2. Anahtar `pk_` ile başlıyor mu kontrol edin
3. Development server'ı yeniden başlatın: `npm run dev`
4. Browser cache'ini temizleyin (Ctrl+Shift+R)

### Hata: "Invalid Clerk API Key"

**Çözüm:**
1. Clerk Dashboard'da API Keys sayfasına gidin
2. Anahtarın aktif olduğunu kontrol edin
3. Doğru environment'ı (test/live) kullandığınızdan emin olun
4. Anahtarı yeniden kopyalayıp yapıştırın (boşluk karakteri olmamalı)

### Hata: "Webhook signature verification failed"

**Çözüm:**
1. `CLERK_WEBHOOK_SECRET` doğru mu kontrol edin
2. Webhook URL'inin doğru olduğunu kontrol edin
3. Clerk Dashboard'da webhook'un aktif olduğunu kontrol edin
4. Supabase Edge Function'ın deploy edildiğini kontrol edin

### Hata: "User profile not created after sign up"

**Çözüm:**
1. Webhook'un çalıştığını kontrol edin (yukarıdaki webhook doğrulama)
2. Supabase logs'u kontrol edin:
   - Supabase Dashboard > Edge Functions > clerk-webhook > Logs
3. Database'de `profiles` tablosunu kontrol edin
4. RLS policies'in doğru yapılandırıldığını kontrol edin

---

## 📊 Clerk Dashboard Özellikleri

### User Management
- **Users:** Tüm kullanıcıları görüntüleyin ve yönetin
- **Organizations:** Organizasyon yönetimi (opsiyonel)
- **Sessions:** Aktif oturumları görüntüleyin

### Authentication
- **Email/Password:** E-posta ve şifre ile giriş
- **Social Logins:** Google, Facebook, GitHub entegrasyonu
- **Phone:** SMS ile telefon doğrulama
- **Multi-factor:** 2FA desteği

### Customization
- **Appearance:** Login/signup formlarının görünümünü özelleştirin
- **Localization:** Türkçe dil desteği (uygulama içinde yapılandırılmış)
- **Branding:** Logo ve renk teması özelleştirme

### Analytics
- **Sign-ups:** Günlük/haftalık kayıt istatistikleri
- **Active Users:** Aktif kullanıcı sayısı
- **Sessions:** Oturum süreleri ve aktivite

---

## 💰 Fiyatlandırma

### Free Tier (Development)
- ✅ 10,000 Monthly Active Users (MAU)
- ✅ Tüm authentication yöntemleri
- ✅ Webhooks
- ✅ Email support
- ✅ Test environment

### Pro Plan ($25/month)
- ✅ 10,000 MAU dahil
- ✅ $0.02/MAU sonrası
- ✅ Custom domains
- ✅ Advanced analytics
- ✅ Priority support

### Enterprise (Custom)
- ✅ Unlimited MAU
- ✅ SLA guarantees
- ✅ Dedicated support
- ✅ Custom integrations

**Not:** Development için Free tier yeterlidir. Production'da kullanıcı sayınıza göre plan seçin.

---

## 🔗 Faydalı Linkler

- **Clerk Dashboard:** https://dashboard.clerk.com/
- **Clerk Documentation:** https://clerk.com/docs
- **Clerk React SDK:** https://clerk.com/docs/references/react/overview
- **Clerk Webhooks:** https://clerk.com/docs/integrations/webhooks
- **Supabase Dashboard:** https://supabase.com/dashboard/project/vtztatcglebrnvikvntf

---

## 📞 Destek

### Clerk Desteği
- **Email:** support@clerk.com
- **Discord:** https://clerk.com/discord
- **Documentation:** https://clerk.com/docs

### Uygulama Desteği
- **Admin Panel:** Admin Panel > Settings > Support
- **Logs:** Admin Panel > Logs

---

## ✨ Özet Checklist

Kurulumu tamamlamak için:

- [ ] Clerk hesabı oluşturuldu
- [ ] Yeni uygulama oluşturuldu
- [ ] `VITE_CLERK_PUBLISHABLE_KEY` alındı ve yapılandırıldı
- [ ] `CLERK_SECRET_KEY` alındı ve Supabase'e eklendi
- [ ] Webhook endpoint oluşturuldu
- [ ] `CLERK_WEBHOOK_SECRET` alındı ve Supabase'e eklendi
- [ ] Frontend doğrulaması yapıldı (login formu görünüyor)
- [ ] Backend doğrulaması yapıldı (Clerk Diagnostics)
- [ ] Webhook doğrulaması yapıldı (test event gönderildi)
- [ ] Test kullanıcı kaydı oluşturuldu
- [ ] Profile database'de oluşturuldu

Tüm adımlar tamamlandığında ✅ Clerk entegrasyonu hazır!

---

**Son Güncelleme:** 2026-02-26
**Versiyon:** 1.0
