Kimlik doğrulama
API anahtarı, Bearer başlığı, yetkiler (scope) ve anahtar güvenliği.
API anahtarı
Anahtarlar istfin_live_ ön ekiyle başlar ve 40 karakter devam eder (32 rastgele karakter + 8 karakterlik sağlama). Ham anahtar sadece oluşturulduğu anda gösterilir; sonradan yalnızca ön eki görünür.
Bir anahtar Panel üzerinden oluşturulur, isim verilir, yetkileri (scope) seçilir ve istenirse son kullanma tarihi (1 ile 365 gün) belirlenir. Anahtar istendiği an iptal edilebilir.
Tek bağlantı ve kişisel kullanım
Her abonelik aynı anda tek bir bağlantı içerir: bir API anahtarı ya da bir bağlı uygulama (Claude, ChatGPT gibi). Yeni anahtar oluşturmak ya da yeni bir uygulama bağlamak mevcut bağlantıyı anında kapatır. Aynı anahtarı hem REST API'de hem MCP istemcilerinde (Claude Code, Cursor) kullanabilirsiniz; bu tek bağlantı sayılır.
Anahtar kişiseldir. Borsa İstanbul veri dağıtım kuralları gereği anahtar başkasıyla paylaşılamaz ve alınan veriler üçüncü kişilere aktarılamaz; bağlantı açarken bunu beyan edersiniz. Bir anahtarın aynı anda birden fazla konumdan kullanıldığı tespit edilirse hesap sahibine e-postayla uyarı gider; paylaşım sürerse anahtar iptal edilebilir.
Fiyat verisi istek-cevap yöntemiyle sunulur; sürekli fiyat akışı (WebSocket, SSE) sağlanmaz.
İstekte kullanım
Tercih edilen yöntem Authorization başlığıdır:
curl "https://api.istfin.com/v1/me" \
-H "Authorization: Bearer istfin_live_..."Authorization başlığı gönderemeyen istemciler için X-API-Key başlığı da kabul edilir:
curl "https://api.istfin.com/v1/me" -H "X-API-Key: istfin_live_..."Authorization başlığı varsa X-API-Key yok sayılır. Anahtarı sorgu parametresi olarak göndermek desteklenmez.
Anahtarı tarayıcıya koymayın
Anahtar hesabınız adına istek atar ve günlük kotanızı tüketir. İstekleri kendi sunucunuzdan yapın; anahtarı ortam değişkeninde tutun, depoya işlemeyin.
Yetkiler (scope)
Her anahtar oluşturulurken bir ya da daha fazla yetki alır. Bir uç, anahtarda bulunmayan bir yetki istiyorsa 403 SCOPE_REQUIRED döner.
| Scope | Kapsadığı uçlar |
|---|---|
market:read | /v1/symbols, /v1/symbols/{symbol}, /v1/quotes, /v1/market/movers, /v1/bars/{symbol} |
fundamentals:read | /v1/fundamentals/{symbol}, /v1/financials/{symbol}/{statement}, /v1/ratios/{symbol} |
account:read | /v1/me |
news:read | Ayrılmış; henüz bu yetkiyi kullanan uç yok. |
Doğrulama sırası ve hatalar
İstek şu sırayla değerlendirilir; ilk takılan adım hatayı belirler.
| Adım | Hata |
|---|---|
| Başlık yok | 401 API_KEY_REQUIRED |
| Biçim veya sağlama bozuk | 401 API_KEY_INVALID |
| Anahtar bulunamadı | 401 API_KEY_INVALID |
| Anahtar iptal edilmiş | 401 API_KEY_REVOKED |
| Süresi dolmuş | 401 API_KEY_EXPIRED |
| Plan API içermiyor | 403 API_ACCESS_NOT_IN_PLAN |
| Fatura bilgisi eksik | 400 BILLING_DETAILS_REQUIRED |
| Scope eksik | 403 SCOPE_REQUIRED |
| Dakika / gün limiti | 429 RATE_LIMITED / 429 QUOTA_EXCEEDED (Limitler) |
Geçersiz anahtarla yapılan denemeler IP bazında sayılır: dakikada 20 başarısız denemeden sonra o IP'den gelen istekler 60 saniye boyunca 429 RATE_LIMITED ile reddedilir.
Anahtarınızı kontrol edin
GET /v1/me anahtarın yetkilerini, planı ve bugünkü kullanımı döner. Entegrasyonu doğrulamak için ilk çağrı olarak uygundur. Ayrıntı: Hesap.