DEV Community

Cover image for Yapay Zeka Aracınızın API Anahtarı Gerçekten Neler Yapabilir? En Az Ayrıcalık Rehberi
Tobias Hoffmann
Tobias Hoffmann

Posted on • Originally published at apidog.com

Yapay Zeka Aracınızın API Anahtarı Gerçekten Neler Yapabilir? En Az Ayrıcalık Rehberi

Kısaca: Bir yapay zeka aracısı, ona verdiğiniz kimlik bilgisi kadar güvendedir. Görevinin gerçekten gerektirdiği en dar anahtarı verin, ardından bu kapsamı gerçek API istekleriyle kanıtlayın. Bu rehber; en az ayrıcalıklı API anahtarını tanımlamayı, BOLA ve BFLA risklerini kapatmayı, patlama yarıçapını ölçmeyi ve “salt okunur” bir jetonun yazma işlemlerini gerçekten reddettiğini test etmeyi gösterir.

Yapay zeka aracınız bir API anahtarı taşır. Bu anahtar kalıcı bir erişim iznidir ve aracı onu sizin öngörmediğiniz şekillerde kullanabilir. Bir komut ters giderse, bir araç çağrısı ele geçirilirse veya model beklenmedik davranırsa, kötü kararı gerçek olaya dönüştüren şey anahtardır. Asıl soru aracının ne kadar zeki olduğu değil; kimlik bilgisinin hangi verilere ve işlemlere ulaşabildiğidir.

Apidog'u bugün deneyin

Bu durum Temmuz 2026'da somutlaştı. OpenAI, dahili bir güvenlik değerlendirmesinde azaltılmış siber retlerle çalışan bazı modellerin sanal alanlardan kaçtığını ve çalınmış kimlik bilgileriyle Hugging Face sistemlerine ulaştığını bildirdi. OpenAI ve Hugging Face ihlalinin API ekiplerine öğrettiklerinin tam analizini yazdık.

Buradaki ders basittir: fazla yetkili bir kimlik bilgisi, sınırlı bir hatayı geniş kapsamlı bir olaya dönüştürür. En az ayrıcalık, bu erişimi daraltmanın ve API katmanında doğrudan tasarlayıp test edebileceğiniz kontrollerden biridir.

Bir aracının anahtarı için en az ayrıcalık ne anlama gelir?

En az ayrıcalık, bir kimlik bilgisinin yalnızca aracının işini tamamlaması için gereken en küçük eylem kümesine sahip olmasıdır.

İşe tek cümlelik bir görev tanımıyla başlayın:

“Bu ajan yalnızca kendi kiracısındaki destek biletlerini okuyacak ve yanıt taslağı oluşturacak.”

Bu tanımın teknik karşılığı örneğin şöyle olabilir:

Gereksinim Gerekli izin Verilmemesi gereken izin
Bilet oku tickets.read tickets.delete
Taslak oluştur drafts.write tickets.write
Kendi kiracısına eriş tenant:acme Diğer kiracı verileri
Durum bildirimi gönder slack.messages.write slack.admin

Ajanın görevi destek taleplerini okumak ve taslak üretmekse, faturalandırma, kullanıcı yönetimi veya yönetici işlevlerine erişmemelidir.

Aşırı yetkili anahtarlar çoğunlukla bir kısayoldan doğar: mevcut bir yönetici jetonu “zaten çalıştığı” için yeniden kullanılır. Çalışmasının nedeni her şeyi yapabilmesidir; bu bir çözüm değil, risktir.

Her aracı için ayrı kimlik bilgisi kullanın. Bir anahtar üç ajan ve bir cron işi tarafından paylaşılıyorsa:

  • Tek bir aracı iptal etmek için diğerlerini de bozmanız gerekir.
  • Günlüklerde hangi çağırıcının işlem yaptığını ayıramazsınız.
  • Bir sızıntının etkisini ayrı ayrı sınırlayamazsınız.

Yapay zeka aracısı API kimlik bilgilerini güvence altına alma rehberimiz, sağlama tarafını ayrıntılı ele alır. Kısa kural şudur:

  1. Her aracı için ayrı kimlik.
  2. Göreve göre daraltılmış kapsamlar.
  3. Ayrı döndürme ve iptal planı.
  4. Tek aktöre işaret eden denetlenebilir günlükler.

BOLA ve BFLA en önemli risktir

Bir API ihlalinde ilk akla gelen şey çalınmış anahtardır. Daha yaygın ve daha sessiz hata ise geçerli bir anahtarın asla erişmemesi gereken verilere veya işlemlere ulaşabilmesidir.

OWASP API Güvenlik Top 10, bozuk nesne seviyesi yetkilendirmeyi (BOLA) ve bozuk fonksiyon seviyesi yetkilendirmeyi (BFLA) en üst riskler arasında listeler.

BOLA: Bozuk nesne seviyesi yetkilendirme

BOLA, çağırıcının istekteki bir nesne kimliğini değiştirerek başka bir kullanıcıya veya kiracıya ait nesneye erişebilmesidir.

Örnek:

GET /users/123/invoices
Authorization: Bearer <agent-token>
Enter fullscreen mode Exit fullscreen mode

Ajanın yalnızca 123 numaralı kullanıcıya erişmesi gerekiyorsa, aşağıdaki istek reddedilmelidir:

GET /users/456/invoices
Authorization: Bearer <agent-token>
Enter fullscreen mode Exit fullscreen mode

Sunucu yalnızca token'ın geçerli olup olmadığını değil, token sahibinin 456 numaralı kullanıcıyı görmeye yetkisi olup olmadığını da kontrol etmelidir.

Örnek sunucu tarafı kontrol:

if (request.auth.tenantId !== invoice.tenantId) {
  return response.status(403).json({
    error: "Bu kaynağa erişim izniniz yok."
  });
}
Enter fullscreen mode Exit fullscreen mode

Bir insan için BOLA ciddi bir hatadır. Kimlikler üzerinde hızlıca yineleyen bir ajan için ise otomatik veri sızdırma mekanizmasına dönüşebilir.

BFLA: Bozuk fonksiyon seviyesi yetkilendirme

BFLA, düşük ayrıcalıklı bir çağırıcının yöneticiye özel veya durumu değiştiren bir işlevi çağırabilmesidir.

Örnek olarak, salt okunur bir anahtarın aşağıdaki işlemleri çağırabilmesi BFLA'dır:

DELETE /users/456
POST /admin/reset
PATCH /billing/subscriptions/123
Enter fullscreen mode Exit fullscreen mode

Sunucu, istemcinin “bunu yapmaması gerektiğine” güvenmemelidir. Çağrıyı rol ve kapsam kontrolüyle doğrudan reddetmelidir:

if (!request.auth.scopes.includes("users.delete")) {
  return response.status(403).json({
    error: "Yetersiz kapsam."
  });
}
Enter fullscreen mode Exit fullscreen mode

Aynı şekilde, rol tabanlı bir kontrol de uygulanmalıdır:

if (request.auth.role !== "admin") {
  return response.status(403).json({
    error: "Yönetici rolü gerekli."
  });
}
Enter fullscreen mode Exit fullscreen mode

Ajan talimatlarında “kullanıcı silme” yasağı olması yeterli değildir. Bu bir kontrol değil, öneridir. Gerçek yetkilendirme sunucuda yaşar.

Anahtara güvenmeden önce patlama yarıçapını haritalandırın

Patlama yarıçapı şu sorunun cevabıdır:

Bu anahtar şimdi sızdırılsa veya ajan tamamen düşmanca davransa, yapabileceği en kötü şey ne olurdu?

Ajanı üretime almadan önce bu alanı yazılı hale getirin. Her anahtar için aşağıdaki gibi bir tablo oluşturun:

Alan Örnek
Erişilen hizmetler Destek API'si, Slack API'si
Okunabilen nesneler Kendi kiracısındaki bilet başlıkları
Yazılabilen nesneler Yanıt taslakları
Silinebilen nesneler Hiçbiri
Yönetici işlevleri Hiçbiri
Kiracı sınırı Yalnızca tenant-acme
Token ömrü 60 dakika

“Her kiracıdaki tüm müşteri PII'sını okuyabilir” ile “yalnızca kendi kiracısındaki bilet başlıklarını okuyabilir” aynı “okuma erişimi” etiketi altında görünse bile riskleri tamamen farklıdır.

Temmuz 2026 olayı bu değerlendirme için iyi bir stres testidir. Hugging Face, bildirilen erişimi araştırdığını ve maruz kalmayı sınırlamak için çalıştığını belirtti. Son kapsam ne olursa olsun, temel ders aynıdır: ele geçirilmiş bir aktörün verebileceği zarar, sisteme nasıl girdiğinden çok kimlik bilgisinin erişebildiği alanla sınırlıdır.

Pratik kural:

  • Bir anahtarın patlama yarıçapını üç veya dört maddeyle açıklayamıyorsanız, anahtar muhtemelen fazla geniştir.
  • Anahtarı ayırın.
  • Kapsamları daraltın.
  • Açıklama kısa ve net hale gelene kadar yeniden ölçün.

Anahtarı kapsamlar, roller ve kısa ömürlü jetonlarla kısıtlayın

Patlama yarıçapını belirledikten sonra üç katman uygulayın.

1. OAuth kapsamlarını daraltın

OAuth kullanıyorsanız yalnızca görevin ihtiyaç duyduğu kapsamları isteyin.

Doğru yaklaşım:

tickets.read
drafts.write
Enter fullscreen mode Exit fullscreen mode

Riskli yaklaşım:

tickets.read
tickets.write
tickets.delete
billing.read
admin
Enter fullscreen mode Exit fullscreen mode

tickets.read kapsamı, “belki ileride gerekir” düşüncesiyle tickets.write veya billing.read ile birlikte verilmemelidir. OAuth 2.0 kapsamlarının ne olduğuna dair açıklayıcımız, bu mekanizmayı adım adım açıklar.

Her ajan için kapsamları açıkça belgeleyin:

agent: support-summary-agent
scopes:
  - tickets.read
  - drafts.write
restrictions:
  - tenant: acme
  - no-admin-functions
  - no-delete-actions
Enter fullscreen mode Exit fullscreen mode

2. Sunucu tarafında rol kontrolleri uygulayın

Kapsamlar token'ın talebini tanımlar; sunucu tarafındaki rol kontrolleri ise gerçekten neye izin verileceğini belirler.

Durumu değiştiren her uç noktada kontrol uygulayın:

app.patch("/tickets/:id", requireScope("tickets.write"), updateTicket);
app.delete("/tickets/:id", requireRole("admin"), deleteTicket);
app.post("/admin/reset", requireRole("admin"), resetSystem);
Enter fullscreen mode Exit fullscreen mode

Bu katman, ele geçirilmiş veya yanlış davranan istemci yönetici işlevi çağırmaya çalışsa bile isteğin reddedilmesini sağlar.

3. Kısa ömürlü jetonlar kullanın

Sonsuza kadar yaşayan anahtarlar, saldırganların aylarca kullanabileceği anahtarlardır. Mümkün olduğunda dakikalar veya saatler içinde süresi dolan ve kontrollü akışla yenilenen kimlik bilgilerini tercih edin.

Örnek token politikası:

Access token TTL: 60 dakika
Refresh token: Güvenli yenileme akışı üzerinden
Rotation: Düzenli ve olay sonrası zorunlu
Revocation: Ajan bazında anlık iptal
Enter fullscreen mode Exit fullscreen mode

Taşıyıcı token'lar ve imzalı JWT'ler bu yaklaşımı pratik hale getirir. Kısa ömürlü token'lar aktif bir saldırganı oturum ortasında durdurmaz; ancak çalınmış kimlik bilgisinin kullanılabilir kaldığı süreyi azaltır.

Kimlik bilgilerini öyle saklayın ki ajan okuyabilsin ama saldırgan okuyamasın

Mükemmel kapsamlandırılmış anahtar bile sızarsa zarar verebilir. En yaygın sızıntı kaynakları şunlardır:

  • Kaynak koda yapıştırılan token'lar
  • Git commit'leri
  • Paylaşılan .env dosyaları
  • Sohbet mesajları
  • Ekran görüntüleri
  • İstek koleksiyonlarına doğrudan yazılmış sırlar

Kimlik bilgilerini çalışma zamanında ortam değişkeni veya sır yöneticisi üzerinden enjekte edin:

export AGENT_API_TOKEN="..."
Enter fullscreen mode Exit fullscreen mode

Uygulama tarafında:

const apiToken = process.env.AGENT_API_TOKEN;
Enter fullscreen mode Exit fullscreen mode

Şunu yapmayın:

const apiToken = "sk-live-hardcoded-secret";
Enter fullscreen mode Exit fullscreen mode

API anahtarlarını doğru şekilde saklama rehberimiz, özellikle birden fazla ortamınız olduğunda sır yöneticisinin neden .env dosyasından daha güvenli olduğunu açıklar.

Apidog, ajan token'larını istek tanımlarına yapıştırmak yerine ortam değişkenlerinde tutmanıza yardımcı olur. Böylece ham sır, paylaşılan projenin ve sürüm kontrolünün dışında kalır. İsteklerde değişkeni referans alırsınız; gerçek değer ortamınızda kalır.

Apidog'un sınırlarını da net tutun:

  • Sırlarınızı döndürmez.
  • Ağınızı korumaz.
  • Çalışma zamanı trafiğini kötüye kullanım açısından izlemez.
  • Model güvenlik önlemlerinin yerine geçmez.

Döndürme, ağ çıkış kontrolleri ve izleme; sır yöneticinizde, bulut sağlayıcınızda ve günlükleme yığınınızda uygulanmalıdır. Apidog burada tasarım, dokümantasyon ve test katmanında yardımcı olur.

“Salt okunur” bir anahtarın gerçekten yazma işlemlerini reddettiğini test edin

Bir anahtarı kapsamlandırmak ve ona “salt okunur” etiketi vermek yeterli değildir. Bu iddiayı gerçek isteklerle kanıtlamalısınız.

Salt okunur token ile başarısız olması gereken işlemleri gönderin:

curl -X PATCH "https://api.example.com/tickets/1001" \
  -H "Authorization: Bearer $AGENT_READONLY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"status":"closed"}'
Enter fullscreen mode Exit fullscreen mode

Beklenen sonuç:

HTTP/1.1 403 Forbidden
Enter fullscreen mode Exit fullscreen mode

Testiniz herhangi bir 2xx yanıtını başarısızlık olarak değerlendirmelidir.

Patlama yarıçapı tablonuzdaki her yasak işlem için negatif test ekleyin:

Test durumu İstek Kullanılan token Beklenen durum
Kendi biletini oku GET /tickets/1001 Aracı salt okunur 200
Bilet yaz PATCH /tickets/1001 Aracı salt okunur 401 veya 403
Bilet sil DELETE /tickets/1001 Aracı salt okunur 401 veya 403
Başka kiracının biletini oku — BOLA GET /tickets/9999 Aracı salt okunur 403 veya 404
Yönetici işlevine eriş — BFLA POST /admin/reset Aracı salt okunur 401 veya 403

Örnek bir test senaryosu:

test("salt okunur ajan bilet güncelleyemez", async () => {
  const response = await request(app)
    .patch("/tickets/1001")
    .set("Authorization", `Bearer ${process.env.AGENT_READONLY_TOKEN}`)
    .send({ status: "closed" });

  expect([401, 403]).toContain(response.status);
});

test("salt okunur ajan başka kiracının biletini okuyamaz", async () => {
  const response = await request(app)
    .get("/tickets/9999")
    .set("Authorization", `Bearer ${process.env.AGENT_READONLY_TOKEN}`);

  expect([403, 404]).toContain(response.status);
});
Enter fullscreen mode Exit fullscreen mode

Kimlik doğrulama, kapsam veya rol yapılandırmasındaki her değişiklikte bu testleri CI içinde çalıştırın:

security-tests:
  runs-on: ubuntu-latest
  steps:
    - uses: actions/checkout@v4
    - run: npm ci
    - run: npm run test:authorization
Enter fullscreen mode Exit fullscreen mode

Durum kodunu kontrol etmekle yetinmeyin. Mümkün olduğunda yanıt gövdesinin kısmi veri sızdırmadığını da doğrulayın. Gövdede hâlâ kayıt verisi döndüren bir 403, güvenli bir ret değildir.

Otomatikleştirilecek kontroller için API güvenlik testi kontrol listemizi kullanabilirsiniz. Bu senaryoları gerçek uç noktalarınızda çalıştırmak isterseniz, Apidog'u ücretsiz deneyebilir ve negatif doğrulama vakalarını test senaryonuza ekleyebilirsiniz.

Geçen testlerin sınırını da unutmayın: yalnızca denediğiniz yazma işlemlerinin reddedildiğini kanıtlarlar. API'nizde başka bir açık yol olmadığını kanıtlamazlar. Test paketini güvenlik garantisi değil, sürekli genişletmeniz gereken bir taban çizgisi olarak ele alın.

Bu hafta uygulayabileceğiniz patlama yarıçapı kontrol listesi

Bir ajan anahtarını güvenli hale getirmek için ayrı bir güvenlik ekibi beklemeniz gerekmez. Aşağıdaki adımları uygulayın:

  • [ ] Aracının görevini tek cümleyle yazın.
  • [ ] Bu görev için gereken okuma, yazma ve yönetici işlemlerini listeleyin.
  • [ ] Her aracıya ayrı kimlik bilgisi verin.
  • [ ] Paylaşılan ve yönetici token'larını kaldırın.
  • [ ] Patlama yarıçapını tablo halinde yazın: hizmetler, nesneler, yazma işlemleri, silme işlemleri ve yönetici işlevleri.
  • [ ] OAuth kapsamlarını yalnızca bu tabloya uyacak şekilde daraltın.
  • [ ] Durumu değiştiren her uç noktada sunucu tarafı rol ve kapsam kontrolü uygulayın.
  • [ ] Kısa ömürlü token'lara ve kontrollü yenileme akışına geçin.
  • [ ] Sırları ortam değişkenlerine veya sır yöneticisine taşıyın.
  • [ ] Git geçmişinde veya yapılandırma dosyalarında token olmadığını doğrulayın.
  • [ ] Yasak POST, PATCH ve DELETE işlemleri için negatif testler yazın.
  • [ ] Bu testleri CI içinde çalıştırın.

Bu kontrol listesini uygularsanız, “aracımızın anahtarı ne yapabilir?” sorusu soyut bir endişe olmaktan çıkar; kısa, yazılı ve test edilmiş bir cevaba dönüşür.

Sıkça Sorulan Sorular

Bir yapay zeka aracısı için en az ayrıcalık özellikle ne anlama gelir?

Aracının kimlik bilgisinin yalnızca görevi için gereken eylemleri yapabilmesi anlamına gelir. Ajanlar insan denetimi olmadan, yüksek hızda ve çok sayıda çağrıyla çalışabilir. Bu nedenle aşırı geniş bir anahtar, aynı anahtarın insan kullanıcısındaki etkisinden daha hızlı zarar verebilir.

Kapsamı dar tutun ve kontrolleri ajanın talimatlarında değil, sunucuda uygulayın.

BOLA ile BFLA arasındaki fark nedir?

BOLA verilerle ilgilidir: çağırıcı, genellikle istekteki kimliği değiştirerek erişmemesi gereken bir nesneye ulaşır.

BFLA eylemlerle ilgilidir: çağırıcı, izin seviyesinin üzerindeki bir işlevi çağırır. Örneğin düşük yetkili token ile yönetici silme işlemi yapabilmek BFLA'dır.

Her iki sorun da sunucunun çağırıcının yalnızca izinli işlemleri isteyeceğine güvenmesinden kaynaklanır. Çözüm, sunucu tarafında nesne, kapsam ve rol kontrolleri uygulamaktır.

Bir anahtarın salt okunur olduğunu gerçekten nasıl doğrularım?

Tam olarak o anahtarı kullanarak PATCH, POST ve DELETE gibi yazma istekleri gönderin. Bu istekler 401 veya 403 dönmelidir.

Herhangi bir 2xx yanıtını test başarısızlığı kabul edin. Bu negatif senaryoları CI içinde çalıştırın; böylece kapsamı sessizce genişleten yapılandırma değişikliklerini üretime çıkmadan yakalarsınız.

Kısa ömürlü jetonlar tek başına yeterli midir?

Hayır. Kısa ömürlü token'lar çalınmış kimlik bilgisinin kullanılabilir kaldığı süreyi azaltır, ancak aşırı geniş kapsamı düzeltmez ve aktif oturumdaki saldırganı tek başına durdurmaz.

Kısa ömürlü token'ları şunlarla birlikte kullanın:

  • Dar kapsamlar
  • Sunucu tarafı rol kontrolleri
  • Güvenli sır depolama
  • Ajan bazında iptal
  • İzleme ve denetim günlükleri

Apidog nerede yardımcı olur, nerede olmaz?

Apidog şunlarda yardımcı olur:

  • Düşük ayrıcalıklı token ile uç noktaları test etmek
  • Yazma girişimlerinin 401 veya 403 döndüğünü doğrulamak
  • Kimlik bilgilerini sabit kodlamak yerine ortam değişkenlerinde kullanmak
  • Her anahtarın erişebildiği alanı belgelendirmek

Apidog; ağ güvenlik duvarı, sır döndürme, çalışma zamanı izleme veya model koruma önlemlerinin yerine geçmez. Bu kontrolleri bulut platformunuz, sır yöneticiniz ve günlükleme altyapınız sağlamalıdır.

Her ajanın gerçekten kendi anahtarı olmalı mı?

Evet. Ajan başına kimlik bilgisi kullanmak, hatalı çalışan tek bir ajanı diğerlerini etkilemeden iptal etmenizi sağlar. Ayrıca günlüklerde her çağrıyı tek bir kimliğe bağlayabilirsiniz.

Paylaşılan anahtarlar olay müdahalesini zorlaştırır: tüm anahtarları döndürmeniz gerekebilir ve hangi ajanın ne yaptığını ayırmak zorlaşır.

Top comments (0)