admin/38980-vm
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
38980-vm/app-9w9pd00g5j41/CLERK_SETUP_GUIDE.md
Flatlogic Bot 6bd90312de Initial import
2026-03-04 18:25:09 +00:00

10 KiB
Raw Permalink Blame History

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:
# Clerk Authentication
VITE_CLERK_PUBLISHABLE_KEY=pk_test_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
  1. Dosyayı kaydedin
  2. Development server'ı yeniden başlatın:
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

📞 Destek

Clerk Desteği

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