API Dokümantasyonu Güvenliği: Git'teki Spesifikasyonlarınız Güvende mi?

API dokümantasyonu güvenliği, çoğu ekibin API güvenliği denetimlerinde atladığı bir yüzeydir. API’nizi kimlik doğrulama, rate limit ve güvenlik testleriyle koruyabilirsiniz; ancak OpenAPI dosyanız, Swagger UI sayfanız veya kimlik doğrulama akışını anlatan markdown belgeleriniz çoğu zaman eski bir Git deposunda ya da yıllardır kimsenin incelemediği statik bir host üzerinde durur. 20 Mayıs 2026’da GitHub, saldırganların yaklaşık 3.800 dahili kod deposundan veri çaldığını doğruladı. Giriş noktası, bir GitHub çalışanının dizüstü bilgisayarına yüklenen zararlı bir VS Code uzantısıydı. Bu olay şu soruyu sormak için iyi bir neden: Yayınladığınız API belgeleri sessizce değiştirilseydi bunu siz veya API tüketicileriniz fark eder miydi?

Apidog'u bugün deneyin

Özet

Güvenli API dokümantasyonu; belgelerinizin erişim kontrolüne, sürüm geçmişine, doğrulanabilir bütünlüğe ve denetim izine sahip olması demektir. Böylece güvenliği ihlal edilmiş bir depo veya host, geliştiricilere yanlış endpoint’ler, token’lar ya da kimlik doğrulama talimatları sunamaz.

Docs-as-code yaklaşımı birçok ekip için faydalıdır: review, geçmiş ve CI entegrasyonu sağlar. Ancak şu durumlarda risk üretir:

• Depo herkese açıktır veya erişim kontrolü zayıftır.
• Eski OpenAPI spesifikasyonları canlı API’den sapmıştır.
• “Sadece doküman” denilerek değişiklikler yeterince incelenmez.
• Yayınlanan site ile incelenen kaynak arasında bütünlük kontrolü yoktur.

Apidog gibi yönetilen bir dokümantasyon katmanı; parola koruması, IP/e-posta beyaz listesi, özel alan adı, sürümleme ve API tasarımıyla senkronize dokümantasyon sağlayarak bu boşlukları azaltır.

GitHub ihlali neden API belgelerinizi denetlemeniz gerektiğini gösteriyor?

GitHub olayı paniğe değil, denetime yol açmalı. TeamPCP adlı tehdit grubu GitHub’ın dahili depolarını sızdırdı ve veri setini yeraltı forumunda 50.000 dolardan fazla bir fiyatla satışa çıkardı. BleepingComputer’ın haberine göre, kötü amaçlı VS Code uzantısı resmi marketplace üzerinden geldi ve bir çalışanın cihazında çalıştı. GitHub, dahili depolar dışında saklanan müşteri verilerinin etkilendiğine dair kanıt bulunmadığını ve soruşturmanın sürdüğünü belirtti.

Bu olay, API dokümantasyonunuzun şu sorularla denetlenmesi gerektiğini gösterir:

• Belgeler nerede tutuluyor?
• Kim yazma yetkisine sahip?
• Yayınlanan içerik review’dan geçen kaynakla aynı mı?
• Belgeler herkese açık mı, yoksa gerçekten erişim kontrollü mü?
• Canlı API ile dokümantasyon arasında drift var mı?

Çoğu ekip bu soruları hiç sormaz. Üç yıl önce Swagger UI GitHub Pages’a yayınlanır, bir CNAME bağlanır ve süreç unutulur. Depo herkese açıktır. Spesifikasyon, en son merge edilen dosyadır. Dokümantasyon değişiklikleri, uygulama kodu kadar dikkatli incelenmez.

Bu tehlikelidir çünkü API dokümantasyonu talimattır. Bir geliştirici API’nizle entegre olurken endpoint yollarını, istek şemalarını, auth header’larını ve örnek kodları doğrudan belgelerinizden kopyalar. Bir saldırgan bu talimatları değiştirebilirse, yalnızca bir web sayfasını bozmaz; başkalarının production ortamında çalıştıracağı kodu etkiler.

Benzer bir güven yüzeyi riskini Vercel ihlalinden alınan API güvenlik dersleri hakkındaki yazımızda ele aldık.

Bu yazıda dört konuya odaklanacağız:

1. Ele geçirilmiş API belgeleri tüketicilerinize nasıl zarar verir?
2. Git’te docs-as-code ne zaman uygundur, ne zaman risklidir?
3. “Güvenli API dokümantasyonu” pratikte hangi kontrolleri gerektirir?
4. Yönetilen bir dokümantasyon katmanı bu boşlukları nasıl kapatır?

İlgili iki yazı:

• GitHub ihlalinin kendi kendine barındırılan API araçları için anlamı
• VS Code uzantısı API anahtarı güvenliği

API belgeleri deponuz veya host’unuz ele geçirilirse ne olur?

API dokümantasyonunuz genellikle üç yüzeyde yaşar:

1. Git deposu
2. Dokümantasyonu oluşturan CI/CD hattı
3. Statik siteyi veya dokümantasyon portalını sunan host

Bu yüzeylerden biri ele geçirilirse aşağıdaki senaryolar gerçekleşebilir.

1. Dokümantasyon değişikliği production koduna ulaşır

En tehlikeli senaryo budur. Saldırgan, belge deposuna veya yayınlanan siteye küçük bir değişiklik yapar:

• https://api.payments.acme.com/v2/charge yerine kendi domain’ini yazar.
• “Başlarken” sayfasındaki örnek bearer token’ı değiştirir.
• OAuth token exchange URL’sini farklı bir host’a yönlendirir.
• SDK örneğine zararlı bir proxy endpoint’i ekler.

Sayfa hâlâ render edilir. CI hâlâ geçer. YAML hâlâ geçerlidir. Ancak API’nizle entegre olan bir sonraki geliştirici bu yanlış endpoint’i kendi servisine kopyalayabilir.

Örnek OpenAPI parçası:

paths:
  /v2/payment-intents:
    post:
      summary: Create a payment intent
      servers:
        - url: https://api.acme-pay.com
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentIntentRequest'
      responses:
        '201':
          description: Payment intent created

Buradaki tek satırlık değişiklik yeterlidir:

servers:
-  - url: https://api.acme-pay.com
+  - url: https://api-acme-pay.example-attacker.com

Eğer tüketiciler OpenAPI dosyasından client generate ediyorsa, yeni client artık istekleri saldırganın domain’ine gönderebilir.

Bu yüzden dokümantasyon diff’leri “sadece belge” olarak görülmemelidir. Endpoint URL’leri, auth akışları, örnek token’lar ve SDK kurulum komutları güvenlik açısından kritik kabul edilmelidir.

2. Dahili ve belgelenmemiş endpoint’ler sızar

Belge depoları zamanla şişer. Herkese açık API spesifikasyonuna şu tür endpoint’ler eklenebilir:

• Dahili admin endpoint’leri
• Debug rotaları
• Partner’a özel işlemler
• Henüz yayınlanmamış beta API’ler
• Feature flag arkasındaki endpoint’ler

Depo herkese açıksa veya yanlışlıkla herkese açılırsa, bu dokümantasyon saldırganlar için hazır bir saldırı haritasına dönüşür.

Özel depo da tek başına yeterli koruma değildir. GitHub ihlalinde olduğu gibi özel depolar dışarı sızarsa, saldırganlar endpoint’lerinizi tahmin etmek zorunda kalmaz; siz onlara şemayı vermiş olursunuz.

Bu tür yüzeyi sistematik denetlemek için 2026 API güvenlik test kontrol listemize bakabilirsiniz.

3. Herkese açık GitHub Pages erişim kontrolü sağlamaz

GitHub Pages statik dosya sunar. Kimlerin okuduğunu bilmez, kimlik doğrulama uygulamaz, erişim iptali yapmaz.

Tamamen herkese açık bir API için bu kabul edilebilir. Ancak belgeleriniz şu gruplardan yalnızca birine görünmeli ise GitHub Pages tek başına yetersizdir:

• Ücretli müşteriler
• Belirli partner’lar
• İç ekipler
• Beta kullanıcıları
• Denetimli kurumsal müşteriler

“Sadece tahmin edilmesi zor URL” erişim kontrolü değildir. URL’ler şu yollarla sızabilir:

• Tarayıcı geçmişi
• Referrer header’ları
• Proxy log’ları
• Paylaşılan yer imleri
• E-posta forward’ları
• Chat mesajları

Bir kişi link’i aldıktan sonra erişimi geri almak da zordur.

4. Eski ve doğrulanamaz dokümantasyon güvenlik riskidir

Her risk saldırgan gerektirmez. Dokümantasyon canlı API’den saparsa tüketiciler yanlış davranışa göre entegrasyon yapar.

Tipik örnekler:

• Endpoint artık v2 altındadır ama doküman hâlâ v1 gösterir.
• Response alanı kaldırılmıştır ama şemada durur.
• Auth header değişmiştir ama örnek kod eskidir.
• Rate limit veya pagination davranışı güncellenmemiştir.

Bu drift, güvenlik ihlalinde daha da problemli olur. Şu soruya cevap veremezsiniz:

Bu endpoint dokümanda hep mi yanlıştı, yoksa biri mi değiştirdi?

Yanıt veremiyorsanız dokümantasyon doğrulanabilir değildir.

Git’te docs-as-code ne zaman uygundur?

Docs-as-code doğru kullanıldığında güçlü bir yaklaşımdır. OpenAPI dosyanızı ve markdown belgelerinizi Git’te tutmak, CI ile Swagger UI veya Redoc üretmek ve statik host’a deploy etmek şu avantajları sağlar:

• Pull request review
• Değişiklik geçmişi
• Kodla birlikte sürümleme
• CI validasyonu
• Otomatik yayınlama
• Geri alma kolaylığı

Soru “Git kullanılmalı mı?” değildir. Soru şudur:

Bu Git tabanlı dokümantasyon kurulumu, bu API için güvenli mi?

Git’te docs-as-code şu koşullarda uygundur

Git tabanlı dokümantasyon genellikle uygundur, eğer:

• API tamamen herkese açıksa.
• Belgelerde gizli veya partner’a özel bilgi yoksa.
• Depoda branch protection açıksa.
• Yazma yetkisi küçük ve denetlenen bir gruptaysa.
• Dokümantasyon PR’ları kod PR’ları kadar dikkatli inceleniyorsa.
• CI/CD hattında sabitlenmiş action’lar kullanılıyorsa.
• Üçüncü taraf CI adımları incelenmişse.
• Deploy credential’ları dar kapsamlıysa.
• OpenAPI spesifikasyonu canlı API’den üretiliyor veya ona karşı doğrulanıyorsa.
• Spesifikasyonu güncel tutmaktan sorumlu bir kişi veya ekip varsa.

Bu koşullar sağlanıyorsa Git geçmişi denetim izi, PR review ise bütünlük kontrolü sağlar.

Git’te docs-as-code şu durumlarda sorumluluğa dönüşür

Aynı yaklaşım şu koşullarda risklidir:

• Belgeler özel olmalı ama host erişim kontrolü sağlamıyorsa.
• “Özel” aslında “link’i bilen görür” anlamına geliyorsa.
• Yazma yetkisi çok genişse.
• CI token’ları ve servis hesapları takip edilmiyorsa.
• Dokümantasyon commit’leri otomatik onaylanıyorsa.
• OpenAPI dosyası elle tutuluyor ve canlı API’den sapıyorsa.
• Aynı depoda public ve internal endpoint’ler birlikte duruyorsa.
• Yayınlanan site ile review’dan geçen kaynak arasında bütünlük kontrolü yoksa.

GitHub ihlali bu riskleri somutlaştırıyor. Saldırı bir geliştirici cihazından başladı ve dahili depolara ulaştı. Eğer özel API spesifikasyonunuz bu depolardan birinde olsaydı, review süreciniz iyi olsa bile şema dışarı sızardı.

Git şeffaflık sağlar; ancak depo çalındığında gizlilik sağlamaz.

Kendi kendine barındırılan dokümantasyon yaklaşımlarını daha detaylı karşılaştırmak için kendi kendine barındırılan API belgeleri karşılaştırmamıza bakabilirsiniz.

“Güvenli API dokümantasyonu” ne anlama gelir?

Güvenli API dokümantasyonu dört kontrolle ölçülmelidir.

1. Erişim kontrolü

Belgeleri yalnızca görmesi gereken kişiler okuyabilmelidir.

Kontrol yöntemleri:

• Parola
• IP beyaz listesi
• E-posta beyaz listesi
• SSO
• Özel giriş
• Rol tabanlı erişim

Pratik test:

Şu anda API belgelerinizi kimlerin okuyabildiğini net olarak söyleyebiliyor musunuz? Bir kişinin erişimini bir dakikadan kısa sürede iptal edebiliyor musunuz?

2. Sürümleme

Her API sürümünün kendi dokümantasyonu korunmalıdır.

Örneğin:

• v1 kullanan tüketici v1 belgelerini görmeli.
• v2 yayınlandığında eski dokümantasyon sessizce ezilmemeli.
• Belirli bir tarihte dokümantasyonun ne söylediği gösterilebilmeli.

Pratik test:

Eski API sürümünüzle entegre olan bir geliştirici, hâlâ doğru eski dokümantasyonu bulabiliyor mu?

3. Bütünlük

Yayınlanan belgelerin yetkili ve doğru kaynaktan geldiğini doğrulayabilmelisiniz.

Bunun için:

• Belgeler kontrollü API tasarımından üretilmeli veya
• PR review zorunlu olmalı ve
• Yayınlanan çıktı incelenen kaynakla eşleşmeli.

Pratik test:

Birisi canlı dokümantasyondaki endpoint URL’sini bir saat önce değiştirseydi bunu fark eder miydiniz?

4. Denetim izi

Şu sorulara cevap verebilmelisiniz:

• Kim değiştirdi?
• Neyi değiştirdi?
• Ne zaman değiştirdi?
• Hangi sürüm yayınlandı?
• Hangi kaynak dosyadan üretildi?

Git geçmişi depo için bunu sağlar; ancak yayınlanan yüzey için de aynı görünürlüğe ihtiyacınız vardır. Deploy adımı ayrı bir saldırı noktasıdır.

Pratik test:

Son 90 güne ait yayınlanmış API dokümantasyonu değişiklik günlüğünü çıkarabiliyor musunuz?

Apidog güvenli API dokümantasyonu için nasıl yardımcı olur?

Apidog; API tasarlama, debug etme, test etme, mock oluşturma ve dokümantasyon yayınlama için hepsi bir arada bir API platformudur. Dokümantasyon tarafı, yukarıdaki kontrolleri sonradan eklenen parçalar yerine platform akışının parçası hâline getirir.

Başlamak için Apidog’u indirin ve API tanımı olan bir proje açın.

1. Kontrollü doğruluk kaynağından dokümantasyon yayınlayın

Apidog’da dokümantasyon, proje içindeki API tasarımından üretilir. Endpoint’leri, şemaları ve kimlik doğrulama yapılarını görsel tasarımcıda tanımlarsınız. Apidog bu tanımdan dokümantasyonu otomatik olarak oluşturur.

Yayınladığınızda şunları içeren etkileşimli bir dokümantasyon sitesi elde edersiniz:

• Endpoint referansı
• “Dene” konsolu
• Çok dilli kod örnekleri
• Request/response şemaları
• Auth bilgileri

Buradaki güvenlik avantajı şudur: Yayınlanan dokümantasyon, ayrı ayrı elle düzenlenen markdown dosyalarından değil, API tanımından gelir. Tasarım değişirse dokümantasyon değişir. Tüketicinin gördüğünü değiştirmek için statik host’taki bağımsız bir dosyayı değil, izinleri ve geçmişi olan API projesini değiştirmeniz gerekir.

2. Dokümantasyon erişim kontrolü uygulayın

Apidog, yayınlanan dokümantasyon için gerçek erişim kontrolleri sağlar:

• Herkese açık: Link’i olan herkes okuyabilir. Tamamen public API’ler için uygundur.
• Parola koruması: Bir parola belirleyip paydaşlarla paylaşabilirsiniz.
• IP beyaz listesi: Erişimi ofis, VPN veya belirli IP aralıklarıyla sınırlayabilirsiniz.
• E-posta beyaz listesi: Belirli e-posta adreslerini veya domain’leri izinli yapabilirsiniz. Örneğin *@sirketiniz.com.
• Özel giriş: Kendi kimlik doğrulama sisteminizi bağlayabilirsiniz. Sunucunuz JWT üretir, Apidog doğrular ve erişimi buna göre verir.

Apidog bu yöntemleri API dokümantasyon erişimini kontrol etme rehberinde açıklar.

Bu kontrol özellikle GitHub Pages boşluğunu kapatır. Link’i bilen herkesin erişebildiği bir statik sayfa yerine, kimlerin okuyabileceğini yönetebilirsiniz.

3. Özel alan adı kullanın

Yayınlanan belgeleri kendi domain’inizde sunabilirsiniz. Örneğin:

developer.sirketiniz.com

Apidog, DNS CNAME veya ters proxy ile özel alan adı kullanımını destekler.

Özel domain tek başına güvenlik kontrolü değildir. Ancak dokümantasyon deneyimini sizin yönettiğiniz ve denetlediğiniz bir alan altında toplar. Bu da tüketiciler için güven sinyalidir.

4. OpenAPI spesifikasyonunu API tasarımıyla senkronize tutun

Dokümantasyon drift’i güvenlik problemidir. Çünkü doğrulanamayan belgeler, tüketicileri yanlış entegrasyonlara yönlendirebilir.

Apidog, API tasarımını doğruluk kaynağı olarak kabul eder ve dokümantasyonu bununla senkronize tutar. Ayrıca şu formatları içe aktarabilir:

• OpenAPI 3.0
• OpenAPI 3.1
• Swagger 2.0

Harici bir spesifikasyon kullanıyorsanız, otomatik güncel kalması için zamanlanmış içe aktarmalar da desteklenir.

Eğer şu anda OpenAPI dosyasını Git deposunda elle tutuyorsanız, en yüksek drift riski burada oluşur. Spesifikasyonu Apidog’a taşıyarak yayınlanan belgelerin kontrol ettiğiniz API tanımına bağlı kalmasını sağlayabilirsiniz.

SwaggerHub’dan geçiş yapan ekipler SwaggerHub API belgelerini Apidog’a taşıma rehberini takip edebilir.

5. Dokümantasyon sürümleme kullanın

Apidog dokümantasyon sürümlemeyi destekler. Böylece birden fazla API sürümünü yan yana yayınlayabilirsiniz.

Örneğin:

• v1 tüketicileri v1 dokümantasyonunu görür.
• v2 yayınlandığında eski dokümantasyon kaybolmaz.
• API evrimi ve belge değişiklikleri takip edilebilir.

Bu, hem sürümleme hem de denetim izi gereksinimlerini karşılar.

Önemli not: Bunların hiçbiri bir geliştirici cihazının ele geçirilmesini tamamen engellemez. Ancak şu sorulara net cevap vermenizi sağlar:

• Belgeleri kim okuyabilir?
• Yayınlanan dokümantasyon API tasarımınızla eşleşiyor mu?
• Hangi sürüm ne zaman değişti?
• Erişimi nasıl iptal edersiniz?
• Eski API sürümleri için doğru belgeler duruyor mu?

GitHub ihlalinden sonra yapılması gereken denetim tam olarak budur.

Dokümantasyon barındırma seçenekleri

Aşağıdaki tablo yaygın yaklaşımları dört güvenlik kontrolüne göre karşılaştırır.

Özellik	Herkese Açık GitHub Pages (Swagger UI / Redoc)	Kendi sunucunuzda barındırılan belgeler	Yönetilen belgeler (Apidog)
Erişim kontrolü	Yok; yalnızca URL belirsizliği	Ne inşa edip sürdürürseniz o	Yerleşik: parola, IP, e-posta, özel giriş
Sürümleme	Manuel; ayrı derlemeler veya dallar	Manuel	Yerleşik; sürümler yan yana yayınlanır
Bütünlük	Git review + geçmiş; zorunluysa	Pipeline güvenliğinize bağlı	Kontrollü API tasarımından üretilen belgeler
Denetim izi	Depo için Git geçmişi; deploy için değil	Loglama yapınıza bağlı	Tasarım ve yayınlanmış belgelerde değişiklik geçmişi
Bakım maliyeti	Düşük kurulum, sürekli pipeline bakımı	Yüksek; tüm yığına siz sahip olursunuz	Düşük; platform host ve geçitleri yönetir
En uygun senaryo	Tamamen public API + disiplinli CI/CD	Sıkı self-hosting veya izolasyon gerektiren ekipler	Operasyonel yük olmadan erişim kontrolü isteyen ekipler

Tek bir doğru seçenek yoktur.

• Tamamen public API ve güçlü CI/CD disiplininiz varsa GitHub Pages yeterli olabilir.
• Katı yerleşim, ağ izolasyonu veya compliance gereksinimleriniz varsa self-hosting mantıklı olabilir.
• Erişim kontrolü, sürümleme ve düşük operasyonel yük istiyorsanız yönetilen dokümantasyon katmanı daha uygundur.

Daha fazla karşılaştırma için:

• Kendi kendine barındırılan API belgeleri karşılaştırması
• Scalar vs SwaggerHub vs Apidog karşılaştırması

Uygulanabilir kontrol listesi

Kendi API dokümantasyonunuzu hızlıca denetlemek için şu adımları izleyin.

1. Yayınlanan tüm dokümantasyon yüzeylerini listeleyin

Örnek:

- GitHub Pages Swagger UI
- docs.sirketiniz.com
- Partner portalı
- Dahili Confluence sayfası
- OpenAPI YAML deposu
- SDK README dosyaları

2. Her yüzey için erişimi kontrol edin

Şunları yazın:

Kim okuyabilir?
Kim yazabilir?
Kim publish edebilir?
Erişim nasıl iptal edilir?

Eğer cevap “link’i bilen herkes” ise bu erişim kontrolü değildir.

3. OpenAPI dosyalarını canlı API ile karşılaştırın

CI içinde basit kontroller ekleyin:

# OpenAPI dosyasını doğrula
npx @redocly/cli lint openapi.yaml

Ek olarak contract test veya schema validation kullanarak canlı API ile spesifikasyonun uyuştuğunu kontrol edin.

4. Dokümantasyon PR’larını güvenlik review kapsamına alın

Aşağıdaki alanlarda değişiklik varsa güvenlik review zorunlu olsun:

servers.url
securitySchemes
authorizationUrl
tokenUrl
example bearer token
SDK installation command
webhook target examples
callback URLs

5. Yayınlanan site ile kaynak arasında bütünlük kontrolü kurun

En azından şu soruya cevap verebilmelisiniz:

Bu canlı dokümantasyon hangi commit’ten üretildi?

Bunu build metadata, footer, deploy log veya release etiketiyle görünür hâle getirin.

6. Private veya partner belgelerini statik public host’tan çıkarın

Eğer belgeler yalnızca belirli kişilere görünmeli ise şunlardan birini kullanın:

• Parola koruması
• IP allowlist
• E-posta allowlist
• SSO
• Özel login

Sonuç

GitHub ihlali, GitHub’dan veya docs-as-code yaklaşımından vazgeçmeniz gerektiği anlamına gelmez. Ancak API dokümantasyonunuzun güvenlik yüzeyi olduğunu hatırlatır.

Bir geliştirici belgelerinizden endpoint, token, auth akışı veya SDK komutu kopyalıyorsa, o belge artık production kodu etkileyen bir kaynaktır.

Sonraki adım:

1. API belgelerinizin yayınlandığı tüm yerleri listeleyin.
2. Her birini erişim kontrolü, sürümleme, bütünlük ve denetim izi açısından değerlendirin.
3. En büyük boşluğu kapatın.
4. Eğer boşluk erişim kontrolüyse, Apidog ile bir proje dokümantasyonunu parola veya e-posta beyaz listesiyle yayınlayarak yönetilen katmanın nasıl çalıştığını test edin.