Kimlik doğrulama ve anahtarlar

Yalnızca abonelere açık

API, ücretli Hear2Text aboneliğine dahildir; ücretsiz planda yoktur. Ayrı bir API ürünü, yalnızca API’ye özel bir fiyat ya da deneme anahtarı yok. Aboneliğiniz yoksa bu sayfaların hepsini okuyabilirsiniz ama gönderdiğiniz her istek şu yanıtı alır:

{
  "error": "subscription_required",
  "message": "The Hear2Text API is included with a paid subscription. Your keys are kept; they will work again as soon as the subscription is active.",
  "docs": "https://heartotext.com/api/docs"
}

Aboneliği ne olursa olsun iki tür hesap API’yi kullanamaz:

• Misafir hesaplar. Misafir hesabın geri kazanılabilir bir kimliği yoktur; uzun ömürlü bir anahtarı böyle bir hesaba bağlayamayız — guest_account_not_supported.
• Kısıtlı hesaplar. Kısıtladığımız bir hesap her istekte account_restricted yanıtını alır.

Anahtar oluşturma

Anahtarları web uygulamasında, kendi oturumunuzla Profil → API sayfasından oluşturursunuz. Anahtar üreten bir endpoint bilerek yok: başka kimlik bilgileri üretebilen bir kimlik bilgisi, tek bir sızıntıyı kalıcı bir sızıntıya çevirir.

Aynı anda en fazla 5 etkin anahtar tutabilirsiniz. İptal ettikleriniz sayılmaz; anahtar yenilemek bu sınıra hiçbir zaman takılmaz.

Anahtarı yalnızca bir kez görürsünüz. Anahtarın kendisini değil hash’ini sakladığımız için onu size yeniden gösterebilecek bir ekran — bizimkiler dahil — hiçbir yerde yok. Kaybederseniz iptal edip yenisini oluşturun.

Anahtarı kullanma

Anahtarı Authorization başlığında gönderin. Başka hiçbir yol kabul edilmiyor: ne sorgu parametresi, ne çerez, ne de kendi tanımladığınız bir başlık. Bağlantının içine konan anahtar; erişim günlüklerine, tarayıcı geçmişine ve referrer başlıklarına düşer.

curl https://heartotext.com/api/public/v1/me \
  -H "Authorization: Bearer h2t_live_a1b2c3d4_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

GET /me, sağlık kontrolü için birebir: planınızı, o anda geçerli olan sınırları ve isteği hangi anahtarın yaptığını söyler.

{
  "plan": "monthly",
  "subscription_status": "active",
  "limits": { "max_recording_seconds": 21600, "daily_seconds": 72000, "concurrent_transcriptions": 5 },
  "usage": { "daily_seconds_used": 3480, "running_transcriptions": 1 },
  "rate_limits": { "requests_per_minute": 120, "creates_per_hour": 60, "creates_per_day": 500, "exports_per_minute": 30 },
  "key": { "name": "Podcast pipeline", "prefix": "h2t_live_a1b2c3d4", "scopes": ["transcriptions:read","transcriptions:write","exports:read"], "workspace": null }
}

Kapsamlar

Her anahtar, oluştururken ona verdiğiniz kapsamları taşır.

Anahtarın kapsamı dışında kalan istek 403 insufficient_scope yanıtını alır; istenen kapsam da gövdede yazar. /me ve /languages için ayrı bir kapsam gerekmez.

Çalışma alanına bağlı anahtarlar

Anahtarı oluştururken tek bir çalışma alanına bağlayabilirsiniz. O anahtarla açılan kayıtlar bu alanda toplanır, anahtar da yalnızca buradaki kayıtları görür. Bağlılık her istekte üyeliğinize bakılarak doğrulanır: çalışma alanından çıktığınız anda anahtar çalışmayı bırakır. Hiçbir alana bağlanmamış anahtar ise kişisel alanınızda çalışır.

İptal, yenileme, aboneliğin bitmesi

• İptal bir sonraki istekte geçerli olur: anahtar her istekte yeniden aranır, önbellekten okunmaz. İptal edilen anahtar bundan sonra hep 401 invalid_api_key yanıtını verir.
• Yenileme şu sırayla yapılır: yeni anahtarı oluşturun, dağıtın, sonra eskisini iptal edin. İkisi bir süre birlikte çalışır; arada boşluk kalmaz.
• Abonelik biterse anahtarlarınız silinmez. Anahtarlarınız, abonelik yeniden etkinleşene kadar subscription_required yanıtı verir; sonra kaldıkları yerden devam eder.
• Şifrenizi değiştirmek anahtarlarınıza dokunmaz; hesabı kurtarmak ise hepsini iptal eder. Anahtar bir oturum bilgisi değil; sıradan bir şifre değişikliği yüzünden üretimdeki bir entegrasyonu kesmek başlı başına bir kesinti olurdu. E-postayla gelen kodla şifre sıfırlamak ise başka bir şey: hesaba başkasının girdiğini düşündüğünüzde başvurduğunuz yol bu, o yüzden her oturumla birlikte her anahtarı da iptal eder. Hesabı silerseniz anahtarlar da gider.

Anahtarı güvende tutmak

• Yalnızca sunucudan. CORS bilerek kapalı; tarayıcıdan yapılan çağrılar desteklenmiyor ve tarayıcıya gönderilen anahtar artık gizli değildir.
• Anahtarı gizli bilgilerinizi tuttuğunuz yerde ya da ortam değişkeninde saklayın; kod deposuna hiç girmesin.
• Mobil uygulamanın token’ı API anahtarı değildir, API anahtarı da oturum değildir; hiçbiri diğerinin alanında iş görmez. Bunun sebebi ikisinin farklı yerlerde saklanması; bir middleware’in ikna edilebileceği bir kural değil.
• Ne Authorization başlığını ne de anahtarın kendisini günlüğe yazıyoruz. Bir anahtarın sızdığını düşünüyorsanız iptal edin; çözümün tamamı bu.