Kimlik Doğrulama

HeptaCert API'si, MCP sunucusu ve CLI'ın tamamı tek bir kimlik doğrulama modeli paylaşır: API anahtarı + scope.

API Anahtarları

HeptaCert API'si Bearer token kimlik doğrulaması kullanır. Her istekte HTTP başlığına anahtarınızı ekleyin:

Authorization: Bearer hc_live_YOUR_KEY

Anahtar Formatı

Anahtar oluşturulduktan sonra yalnızca anahtar ön eki (key prefix) saklanır; tam anahtar yalnızca oluşturma anında bir kez gösterilir. HeptaCert anahtarın kendisini saklamaz — kaybederseniz iptal edip yenisini oluşturmanız gerekir.

Anahtar Oluşturma

Admin panelinde Ayarlar → API Anahtarları sayfasından oluşturulur. Oluşturma sırasında belirlersiniz:

• İsim — anahtarın kullanım amacı (örn. "CI/CD Pipeline", "Zapier Entegrasyonu")
• Scope'lar — izin verilen işlem tipleri (aşağıya bakın)
• Son kullanma süresi (expires_days) — 1–3650 gün; boş bırakılırsa süresiz
• Anahtara özel hız sınırı (rate_limit_per_min) — opsiyonel, 10–10000 istek/dakika

Scope'lar (İzinler)

Scope'lar, bir anahtarın ne yapabileceğini sınırlar. Scope atanmamış bir anahtar tam erişime sahiptir (tüm kaynaklar). Bir veya daha fazla scope atadığınızda, anahtar yalnızca o scope'ların izin verdiği işlemleri yapabilir — kapsam dışı bir istek 403 Forbidden döner.

Minimum Yetki Prensibi

Her entegrasyon için yalnızca gereken scope'ları verin:

• Sadece raporlama yapan bir gösterge paneli → analytics:read, reports:read
• Katılımcı senkronize eden bir CRM entegrasyonu → attendees:read, crm:write
• Yalnızca sertifika yayımlayan bir CI işi → certificates:write

Böylece bir anahtar sızsa bile etki alanı sınırlı kalır.

Scope'lar Tüm Yollarda Geçerli

Scope kısıtlamaları yalnızca REST API'de değil, MCP sunucusunda da uygulanır. Örneğin certificates:write scope'u olmayan bir anahtarla bir AI asistanı issue_certificates aracını çağırırsa, araç çalışmadan reddedilir. Aynı kural CLI için de geçerlidir.

Hız Sınırları (Rate Limiting)

API isteklerine hız sınırı uygulanır. Varsayılan genel sınır dakikada 200 istektir. Anahtar başına özel bir sınır tanımladıysanız (rate_limit_per_min), o anahtar için bu değer geçerli olur.

Sınır, mümkün olduğunda API anahtarı bazında, anahtar yoksa IP adresi bazında uygulanır.

Sınır aşılınca 429 Too Many Requests döner:

{
  "detail": "Rate limit exceeded: 200 per 1 minute",
  "error": "Rate limit exceeded: 200 per 1 minute"
}

İyi Backoff Pratiği

429 aldığınızda kısa bir gecikmeyle üstel geri çekilme uygulayın:

import time
import httpx
 
def request_with_retry(client, *args, max_retries=5, **kwargs):
    for attempt in range(max_retries):
        resp = client.request(*args, **kwargs)
        if resp.status_code != 429:
            return resp
        time.sleep(2 ** attempt)  # 1s, 2s, 4s, 8s, 16s
    return resp

Anahtar Rotasyonu ve İptal

Güvenlik ihlali şüphesi veya rutin rotasyon için:

1. Admin paneli → Ayarlar → API Anahtarları
2. Yeni bir anahtar oluşturun ve ortam değişkenlerinizi/secret'larınızı güncelleyin
3. Geçişi doğruladıktan sonra eski anahtarı devre dışı bırakın (is_active = false) veya silin

İptal edilen/pasifleştirilen anahtarlar derhal geçersiz olur — bekleyen istekler dahil. Anahtar son kullanma tarihi belirlediyseniz, o tarihten sonra otomatik olarak geçersiz olur.

Sonraki Adımlar

• API Referansı →
• MCP ile AI Agent Kurulumu →
• CLI Kurulumu →