AIGENCY API erişim modeli: Token tek başına yeterli, kapsam (scope) seçimi yok

30 Mayıs 2026 — AIGENCY V4.1 ile birlikte gelen yeni endpoint'lerin (Bilgi Bankası, Zamanlanmış Görevler, Derinlemesine Araştırma, Canvas, Mesaj Yeniden Üretme, Sohbet Klasörleri) tamamı artık v2 API üzerinden erişilebilir. Ama hangi token, hangi endpoint'i çağırabilir? Bu yazıda, AIGENCY'nin scope'suz erişim modelini ve neden bu yolu seçtiğimizi anlatacağız.

Karar: scope yok

Uygulamanızı oluştururken size bir form sunmuyoruz: "şu endpoint'lere izin var, bunlara yok" diye kutucuk seçtirmiyoruz. AWS-vari fine-grained IAM yok; Stripe'ın restricted keys'ine benzer bir izin matrisi yok. Bunun yerine basit, iki katmanlı bir model var:

1. Token: Hesabınızdaki API Uygulamalarım sayfasından bir uygulama oluşturursunuz, size 32 karakterlik bir token verilir. Bu token tüm v2 API çağrılarına URL parametresi olarak girer.
2. Paket: Hesabınızın paketi (Pro veya İşletme) hangi özelliklerin açık olduğunu belirler. Free ve Başlangıç paketlerinde API'a erişim yoktur; uygulama oluşturulamaz. Pro ve İşletme paketleri ise tüm V4.1 özelliklerini açar — sadece quota ve limit farkları olur.

Çağrı şu sırayla doğrulanır: token geçerli mi → ait olduğu hesabın paketi bu özelliği destekliyor mu. İkisi de yeşilse, isteğiniz işlenir.

Operasyonel not: Bir özelliği geçici olarak (örneğin altyapı bakımı sırasında) AIGENCY tarafında devre dışı bırakmamız gerekirse, ilgili endpoint 404 döner. Bu durum nadirdir ve hesabınızda kalıcı bir değişiklik anlamına gelmez; sorun giderildiğinde aynı token'la çağrı kaldığı yerden çalışır.

Neden scope koymadık

Scope'lar (kapsamlar) güzel bir fikirdir — yetkisiz erişimi sınırlandırır, log'larda hangi izinle ne yapıldığını izleme imkânı verir. Ama gerçek hayatta üç sürtünme noktası yaratırlar:

• İlk uygulama deneyimi: Bir geliştirici hızlıca bir prototip için API'ya bağlanmak ister. 8 kutucuk seçmek zorunda kalmak hem de "hangisi lazım emin değilim, hepsini seçeyim" davranışına yol açar. Sonuç: scope teorik olarak vardır, pratikte herkes "all" seçer.
• Bakım yükü: Yeni bir endpoint eklediğimizde tüm mevcut token'ların scope listesine eklemek gerekir. Aksi halde kullanıcılar "neden 403 alıyorum" sorusuyla destek hattını arar. Sürüm uyumluluğu kâbusu.
• Hatalı güvenlik hissi: Asıl tehdit, token'ın sızmasıdır. Scope'lu da sızsa, scope'suz da sızsa attacker hesabınızdaki sohbetleri okur, kredi tüketir. Scope, kredinizi kurtarmaz — sadece "hangi endpoint'le tükettiği"ni belirler.

Bunun yerine üç şeyi sıkı tuttuk: kaynak sahipliği (token sadece kendi hesabınızın klasörlerini/KB'lerini/sohbetlerini görür — başkasınınkine 404 döner), rate limit (60 req/dk, abuse tetiklenirse otomatik throttle), ve kredi kotası (paket bittiğinde tüm endpoint'ler 402 döner).

Pratikte ne anlama geliyor

Bir örnek: Tarayıcı ekranınızda API Uygulamalarım sayfasından "Yeni Uygulama" diyorsunuz. Sadece bir ad istiyoruz — "CRM entegrasyonu" diyelim. Token üretilir; z5PDmoNTQ2t5rQeN9oxw6lmkcRBnP7ub gibi bir şey.

Bu token'la yapabilecekleriniz:

• Klasik endpoint'ler (newChat, sendMessage, view-chats, resumeChat, deleteChat, credit, ai-team-list) — paketinizden bağımsız hepsi açık.
• V4.1 endpoint'leri — paketiniz Pro veya İşletme ise hepsi açık. Free ve Başlangıç'ta zaten v2 token alamadığınız için bu durum oluşmaz.

Yani "Bilgi Bankası endpoint'ine bu uygulama erişebilir mi?" sorusunun cevabı şu: Paketiniz Pro veya üzeriyse evet. Ayrı bir izin ayarlamanıza gerek yok.

Quota ve limitler nerede?

Scope yerine, gerçek koruma katmanı kotalardır. Her özelliğin paket bazında bir tavanı vardır:

Kota dolduğunda endpoint 429 veya 403 quota_exceeded döner ve hangi limitin doldurduğu cevap gövdesinde açıkça yazılır. Bu mekanizma, scope'tan çok daha sıkı: scope bir endpoint'i tamamen açar ya da kapatır; kota ise sürekli ölçer ve abuse'u anında tespit eder.

Token sızarsa

Token URL parametresinde geçtiği için tarayıcı history'sinde, proxy log'larında, hata raporlarında izi olabilir. Bu yüzden token'ı asla istemci tarafına (frontend, mobil app embedded, GitHub repo) koymayın. Yalnızca sunucu tarafında saklayın.

Sızmadığınızı düşündüğünüz bir durumda bile şüpheniz varsa, API Uygulamalarım sayfasından eski token'ı silip yeni bir uygulama oluşturun. Eski token o anda iptal olur; sızmış kopyalar artık çalışmaz. Bu, scope yönetiminden çok daha hızlı bir tepki yoludur.

Bir çağrı nasıl yapılır

Klasik bir akış: kredi sorgu → asistanı seç → yeni sohbet → mesaj gönder. cURL ile:

# Kredi sorgu (ücretsiz, sayım yapmaz)
curl https://aigency.dev/api/v2/credit/YOUR_API_TOKEN

# Yeni sohbet (asistan id=16: Alparslan)
curl -X POST https://aigency.dev/api/v2/newChat/16/YOUR_API_TOKEN \
  -H "Content-Type: application/json" \
  -d '{"message": "Merhaba!"}'

# Bilgi Bankası — V4.1, paket Pro/İşletme ise otomatik açık
curl https://aigency.dev/api/v2/knowledge-base/YOUR_API_TOKEN

Üçüncü çağrı, scope ayarlamasaydık çalışmaz mıydı? Hayır. Çünkü scope yok. Token + paket yeşilse, isteğiniz işlenir.

Gelecek: webhook ve daha incelikli kotalar

Webhook altyapısı v3 yol haritasında — görev tamamlandığında, derin araştırma bittiğinde veya kredi belirli bir eşiğin altına düştüğünde uygulamanıza HTTPS POST göndereceğiz. Bu, polling ihtiyacını kaldırır.

Scope konusundaki tutumumuz değişebilir mi? Belki. Eğer çoklu kullanıcı senaryosunda (örneğin bir şirket içinde farklı ekiplerin aynı hesabı kullandığı durumlarda) belirli endpoint'leri kısıtlama talebi yoğunlaşırsa, scope'lu token modeli eklenebilir. Şu an için ihtiyaç görünmüyor — ölçtüğümüz şey API token'ı olan herkesin paketi destekliyorsa her şeyi denemek istemesi.

Ayrıntılı endpoint listesi, kod örnekleri ve OpenAPI/Postman dosyaları için /docs sayfasının API sekmesine bakın.