API anahtarları ve kapsamlar
Public API anahtarları — biçim, app/org kapsamı, kapsam (scope) listesi ve rol kuralı, IP izin listesi, bitiş tarihi, rotasyon, iptal ve en iyi uygulamalar.
API anahtarı (hs_live_ ya da hs_test_ öneki + 40 karakter base62) sunucu tarafı erişim içindir ve Authorization: Bearer başlığıyla gönderilir. Anahtar SHA-256 özetiyle saklanır; ham değer yalnızca oluşturma ve rotasyon yanıtında görünür. Dashboard Organizasyon → API anahtarları ya da POST /v1/apps/{app_id}/api-keys (admin).
Kapsam (scope) listesi
| Kapsam | Yetki | Gerekli üye izni |
|---|---|---|
notifications:write | Bildirim oluşturma/iptal, alıcı tahmini, journey run tetikleme | campaigns.send |
users:read | Kullanıcı, abonelik, alias, bildirim kutusu, tercih, suppression okuma | users.read |
users:write | Kullanıcı/abonelik/alias/tercih/suppression yazma, KVKK silme | users.write |
events:write | Olay gönderme | users.write |
segments:read | Segment listeleme, önizleme, tahmin | users.read |
analytics:read | Raporlar; mesaj/kampanya/journey/şablon/in-app istatistikleri ve listeleri | analytics.read |
mcp:write | MCP yazma araçları: yalnızca kampanya/segment taslağı oluşturur, gönderim yapmaz | campaigns.create, segments.write |
admin | Tüm kapsamlar + kanal kimlik bilgileri, webhook'lar, şablon/kampanya/journey/in-app yönetimi, export/import, API anahtarları, app oluşturma, org/audit okuma | tüm izinler (yalnızca owner/admin) |
Kural: anahtarı oluşturan/düzenleyen/döndüren üyenin rolü, verilen kapsamların gerektirdiği izinlerin hepsine sahip olmalıdır (yetki yükseltme engeli). Her işlemin gerektirdiği kapsam API referansında işlem başlığının altında yazar.
App ve org kapsamı
- App'e bağlı anahtar: yalnızca o app'in kaynakları;
app_idyolda/sorguda/gövdede verilmese de bağlı app kullanılır. - Org geneli anahtar (
app_id: null): tüm app'ler;GET /v1/apps,POST /v1/apps,GET /v1/organization*veusageiçin gerekir.app_scopesile belirli app'lere kısıtlı üyeler org geneli anahtar oluşturamaz.
Alanlar
| Alan | Açıklama |
|---|---|
name | Görünen ad |
scopes[] | En az bir kapsam |
environment | live (varsayılan, önek hs_live_) ya da test (önek hs_test_); üretim/staging entegrasyonlarını ayırmak için kullanılır |
ip_allowlist[] | CIDR (IPv4/IPv6); boşsa sınırsız. Dışındaki istek 403 HS_FORBIDDEN (details.reason: ip_not_allowed). Vekil arkasında TRUST_PROXY ile gerçek IP alınır |
expires_at | Bitiş; geçince 401 HS_UNAUTHENTICATED |
Yaşam döngüsü
| İşlem | Uç |
|---|---|
| Oluştur | POST /v1/apps/{app_id}/api-keys → { id, key, prefix, scopes, … } (ham key yalnızca burada) |
| Liste | GET /v1/apps/{app_id}/api-keys (önek, kapsamlar, son kullanım, bitiş) |
| Güncelle | PATCH …/api-keys/{key_id} (ad, kapsamlar, IP listesi, bitiş) |
| Rotasyon | POST …/api-keys/{key_id}/rotate → yeni ham anahtar; eski anahtar hemen geçersiz |
| İptal | DELETE …/api-keys/{key_id}; iptal önbelleği ≤ 5 sn içinde düşer |
Örnekler: API → API anahtarları. Oluşturma, güncelleme, rotasyon ve iptal denetim kaydına (ad, önek, kapsamlar, IP listesi) yazılır.
Hata yanıtları
| Durum | Kod | Neden |
|---|---|---|
| 401 | HS_UNAUTHENTICATED | Başlık yok/geçersiz, iptal edilmiş ya da süresi dolmuş anahtar, /internal rotasına API anahtarıyla istek |
| 403 | HS_FORBIDDEN | Kapsam yetersiz, IP izin listesi dışı, org geneli gerektiren işlem app anahtarıyla |
| 403 | HS_ORG_SUSPENDED | Organizasyon askıda (yalnızca faturalama okunabilir) |
| 429 | HS_RATE_LIMITED / HS_QUOTA_EXCEEDED | Hız sınırı ya da plan kotası |
En iyi uygulamalar
- Her entegrasyon için ayrı, en dar kapsamlı anahtar;
adminyalnızca yönetim otomasyonları için. - Anahtarı ortam değişkeninde tutun; istemciye, mobil uygulamaya ya da depoya koymayın. Dashboard Loglar ekranı anahtarın son kullanımını gösterir.
- Üretim/staging için
live/testortamlarını ayırın; sızma şüphesinde rotasyon yapın (eski anahtar anında geçersizdir, uygulamanızı yeni anahtarla aynı anda güncelleyin). - Vekil/NAT arkasındaysanız IP izin listesini çıkış IP'lerinizle sınırlayın.
- SDK'larda
baseUrl/apiUrlHTTPS olmalı; bölgesel API köküne yönlendirme (421) SDK tarafından izlenir (veri yerleşimi).
Güvenliğe genel bakış
Pushizo güvenlik modeli — kimlik doğrulama, RBAC, kiracı izolasyonu (RLS), gizli bilgi şifreleme, uygulama güvenliği (SSRF, CSP, imzalar), gözlemlenebilirlik ve denetim kaydı; ASVS kontrol listesi.
KVKK ve GDPR uyumu
Roller (veri sorumlusu/işleyen), hesap sahibi hakları (veri indirme, hesap silme, pazarlama izni), son kullanıcı hakları, kayıt onayı ve sözleşme sürümü, saklama, alt işleyiciler, DPA ve veri yerleşimi.