2026’da Laravel’de API Anahtarlarını Güvenli Bir Şekilde Saklama ve Kullanma Yöntemleri

2026 yılında neredeyse her Laravel projesi OpenAI, Stripe, Telegram, AWS S3, Resend, Brevo gibi 3-10 dış API’yi entegre ediyor.

Ancak birçok anahtar sızıntısı, karmaşık saldırılardan değil, tamamen basit hatalardan kaynaklanıyor: Git’e commit etmek, loglama yapmak, ön uçta kullanmak ya da env() fonksiyonunu üretim ortamında config:cache sonrası çağırmak.

Bugün, “her şey çalışıyor”dan “huzur içinde uyuyorum” noktasına uzanan bir yolculuğa çıkacağız.

1. Temel (ama doğru) seviye — .env + config

Anahtarları kaynak kodunuzda asla sabit kodelemeyin:

// ❌ Kötü
$openai = new OpenAI('sk-123...');

// ✅ İyi
# .env
OPENAI_API_KEY=sk-...
STRIPE_SECRET_KEY=sk_live_...

// config/services.php
return [
    'openai' => [
        'api_key' => env('OPENAI_API_KEY'),
        'organization' => env('OPENAI_ORG'),
    ],

    'stripe' => [
        'key'    => env('STRIPE_KEY'),
        'secret' => env(),
    ],
];

Kullanımı:

$key = config();

// veya tip güvenliği ile (Laravel 11+)
$key = Config::string();

Neden config, env()‘den daha iyidir?

php artisan config:cache çalıştığında, config dosyaları dışındaki her env() çağrısı null döner.
Bu nedenle, her env() yalnızca config/*.php dosyalarında yer almalıdır.

Altın kural:

env() — sadece config dosyalarında.
Diğer her yerde — config('path.to.key').

2. Orta seviye: tipe güvenli yapılandırmalar + DTO

Bir düz string kırılgandır. Bunu güçlü bir şekilde tiplenmiş hale getirelim.
Bir değer nesnesi oluşturun:

// app/Config/OpenAiConfig.php
final readonly class OpenAiConfig
{
    public function __construct(
        public string $apiKey,
        public ?string $organization = null,
        public string $baseUrl = ,
    ) {
        if (empty($this->apiKey)) {
            throw new RuntimeException();
        }
    }

    public static function make(): self
    {
        return new self(
            apiKey: Config::string(),
            organization: Config::string(, null),
        );
    }
}

Bunu bir singleton olarak kaydedin:

// app/Providers/AppServiceProvider.php
public function register(): void
{
    $this->app->singleton(OpenAiConfig::class, fn () => OpenAiConfig::make());
}

Her yerde kullanım:

$openai = app(OpenAiConfig::class);

$client = OpenAI::client($openai->apiKey, $openai->organization);

Faydaları:

• Alanlar için IDE otomatik tamamlama
• Üretim ortamında değil, başlangıçta başarısız olma
• Mocklamak / test etmek kolay

3. Sıfır kesinti ile anahtar döngüsü

API sağlayıcıları (OpenAI, Anthropic, Stripe, AWS) anahtarların her 90 günde bir döndürülmesini önerir.
Ancak, anahtarı .env dosyasında basitçe değiştirmek şöyle bir sorun yaratır: her talep başarısız olur.

Basit bir geri dönüş yaklaşımı:

# .env
OPENAI_API_KEY_CURRENT=sk-abc123...
OPENAI_API_KEY_OLD=sk-oldkey...

// app/Services/OpenAiService.php
class OpenAiService
{
    private array $keys;

    public function __construct()
    {
        $this->keys = [
            Config::string(),
            Config::string(, null),
        ];
    }

    public function client(): \OpenAI\Client
    {
        foreach ($this->keys as $key) {
            if ($key === null) continue;

            try {
                $client = OpenAI::client($key);
                $client->models()->list(); // hızlı doğrulama
                return $client;
            } catch (\Exception $e) {
                // logla ve bir sonrakine geç
            }
        }

        throw new RuntimeException();
    }
}

Çok daha iyi — zaman aşımı (AWS / Laravel şifrelemesi gibi):

1. Yeni anahtarı CURRENT olarak ekleyin
2. Eski anahtarı FALLBACK_1, FALLBACK_2… şeklinde tutun
3. Eski anahtarı 1-2 saat sonra (veya deploy sonrasında) kaldırın

Otomatik döngü için, laravel-locksmith gibi paketleri düşünün (AWS gizli anahtarları / diğer sağlayıcılarla sıfır kesinti döngüsü).

4. Üretim için geliştirmeler

API anahtarları için sağlık kontrolü
Bir /health (veya /up) rotası ekleyin:

// routes/health.php
Route::get(, function () {
    $status = [
        => Config::string() ? : ,
        => Config::string()  ? : ,
        // ...
    ];

    $missing = array_keys(array_filter($status, fn($v) => $v === ));

    if ($missing) {
        abort(500, . implode(, $missing));
    }

    return response()->json([
        => ,
        => $status,
    ]);
})->name();

Kubernetes, Laravel Forge, Ploi bu uç noktayı izleyebilir.

Laravel Pennant + özellik bayrakları

Bir anahtarı geçici olarak devre dışı bırakın:

Pennant::define(, fn () => env(, true));

if (Pennant::active()) {
    // kullanın
} else {
    // geri dönüş / mock
}

5. 2026 Anti-düzenleri (bunu yapmayın)

• env('KEY') kullanımı controller/layers içinde config:cache sonrası
• Şifreleme olmadan veritabanında anahtar saklamak (encrypt() / Crypt::)
• .env’yi git’e commit etmek
• Anahtarları ön uca göndermek (hatta VITE_ env aracılığıyla bile)
• Fallback olmadan 429 / geçersiz anahtar hatalarını göz ardı etmek
• Tüm ortamlar için aynı anahtarı kullanmak

Ön dağıtım kontrol listesi

1. Tüm anahtarlar .env içinde – .env git’te yok
2. env() çağrıları yalnızca config/*.php içinde bulunuyor
3. php artisan config:cache üretim ortamında çalışıyor
4. Config::string() / tipli config yöntemleri kullanıyorsunuz
5. Her hizmet için DTO / singleton oluşturulmuş
6. Fallback veya döngü uygulanmış
7. /health rotası API anahtarlarını kontrol ediyor
8. Loglarda anahtar yok (kontrol config/logging.php)

Projelerinizi hemen kontrol edin — bir kayıp anahtar size büyük kayıplara mal olabilir.
Anahtarlarınızı nasıl saklıyor ve döndürüyor musunuz?
Yorumlarda yöntemlerinizi paylaşın — belki daha temiz bir çözümünüz vardır!
Bu faydalı ise — bir ❤️ verin ve kaydedin.
Güvenli dağıtımlar! 🔐