Authentication

Teknik Danışman REST API'sine erişmek için tenant-scoped Bearer token kullanılır. Bu rehber ilk key'inizi üretip ilk başarılı isteğinizi atmanız için adım adım yürütür.

Hızlı başlangıç

1

API Keys sayfasına girin

Panel'e admin yetkisiyle giriş yapın → sol menüden API & Webhooks → API Anahtarları.

Tenant başına ayrı key — paylaşılan SaaS ortamında her müşterinin key'i kendi DB'sine erişir, cross-tenant okuma yok.

2

Yeni key oluşturun

"Yeni Anahtar" → açıklayıcı bir label yazın (örn. fatura-otomasyonu-prod). Bu sadece sizin tanıyabilmeniz için.

Scope seçin (aşağıda detay var):

  • read — sadece GET
  • write — POST/PUT/DELETE
  • admin — read + write (en geniş)

Çoklu scope seçebilirsiniz (örn. read + write).

3

Key'i bir defaya mahsus kopyalayın

Yanıt ekranında full token yalnızca bir kez gösterilir. Format:

tdk_a1b2c3d4e5f67890abcdef0123456789abcdef01

Yapı: tdk_ (prefix) + 8 hex (ID, panel listesinde görünür) + 32 hex (secret, sadece SHA-256 hash'i saklanır).

⚠️ Token'ı kaybederseniz Geri alamazsınız — yalnızca prefix gösterilir, secret asla. Eski key'i iptal edip yenisini üretin.
4

İlk isteğinizi atın

Health-check ile başlayın:

curl -i https://teknikdanisman.net/api/v1/ping.php \
  -H "Authorization: Bearer tdk_..."

Başarılı yanıt:

HTTP/1.1 200 OK
Content-Type: application/json
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 99
X-RateLimit-Reset: 1718983800

{"ok":true,"api_version":"v1","service":"teknik-danisman","time":"2026-06-22T14:30:01Z"}

Scope sistemi

Her endpoint en az bir scope gerektirir. Key'in admin scope'u varsa hepsine erişir.

ScopeErişimTipik kullanım
read GET /customers.php, /employees.php, /hardware.php, /ping.php Salt-okunur dashboard'lar, raporlama, veri ihracı
write POST/PUT/DELETE — kayıt oluşturma, güncelleme, silme; /renew.php Otomatik provisioning, CRM senkronizasyonu, dış sistemden kayıt yaratma
admin Yukarıdaki tüm erişimler + ileride eklenecek hassas endpoint'ler Yalnızca güvenilir backend servisler. Müşteri uygulamalarında kullanmayın.
En az ayrıcalık prensibi Yalnızca okuyacak entegrasyonlar için read yeterli — yazma yetkisi vermeyin. Compromised key'in zararı scope kadar büyüktür.

Güvenlik en iyi pratikleri

Rotation (kural: 90 günde bir)

Düzenli rotation güvenlik ihlali penceresini küçültür. Önerilen prosedür:

  1. Aynı scope ile yeni key oluşturun (örn. fatura-prod-v2).
  2. Entegrasyon konfigürasyonunda yeni key'i kullanın, deploy edin.
  3. Yeni key'in başarılı çalıştığını doğrulayın (audit log → istek var mı?).
  4. Eski key'i iptal edin (API Keys → "İptal Et"). Geri alınamaz.
Webhook secret rotation'ı farklıdır Webhook secret değiştirildiğinde eski secret 72 saat boyunca X-TD-Signature-Previous header'ında gönderilir. Detay: Webhook Catalog → Secret rotation.

Rate limit

Key başına 100 istek / dakika (sliding window). Her başarılı yanıtta:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 73
X-RateLimit-Reset: 1718983800     # epoch (UTC saniye)

Aşıldığında 429 + Retry-After: 60. Üretim entegrasyonları Remaining'i izleyip backoff uygulamalı.

Sık sorulanlar

Key'i hangi tenant'a bağlı bilmek için ne yapmalıyım?

API Keys sayfasında her key'in altında oluşturulduğu tenant + tarih + scope listesi gösterilir.

Bir key birden fazla tenant'a erişebilir mi?

Hayır. Her key tek tenant'a bağlıdır. Çok tenant entegrasyonu için tenant başına ayrı key üretin.

Key'i istemci taraflı bir uygulamada (SPA, mobil) kullanabilir miyim?

Hayır, asla. Browser DevTools veya APK decompile ile key dışarı sızar. Bunun yerine kendi backend'inizde proxy/middleware kurun.

Key süre dolar mı?

Default'ta süresiz aktiftir. İptal edilene kadar çalışır. Üretim uygulaması için 90 günde bir rotation önerilir.

Sonraki adımlar