Kimlik Doğrulama

Public Partner API, onaylı organizasyonlara verilen Bearer kimlik bilgilerini kullanır. Anahtarlar yalnızca sunucu tarafında saklanmalı ve kullanılmalıdır.

API anahtarları registry kontrollü kimlik bilgileridir. Onaylı sandbox, pilot veya private-beta capability'yi tanımlarlar; public self-servis trafik anahtarı değildir ve tek başına external GA erişimi açmazlar.

---

Anahtar aileleri

Anahtar ailesi	Ön ek	Güncel kullanım
Partner V2	ntp_partner_v2_<key-id>_*	Onaylı private-beta partner rotaları; V1 anahtarlar kabul edilmez
Agent V2	ntp_agent_v2_<key-id>_*	Cihaza bağlı Edge Agent rotaları; mutasyonlarda sender proof gerektirir

---

İstek formatı

Public Partner OpenAPI rotaları için anahtarı Authorization başlığında gönderin:

POST /api/v1/estimate HTTP/1.1
Host: api.nowtoprint.com
Authorization: Bearer ntp_test_xxxxxxxxxxxxxxxxxxxx
Accept: application/json
Content-Type: application/json

Bazı private-beta control-plane endpoint'leri açık registry key header'ları kullanır. Webhook yönetimi (/api/v1/webhooks) şunları gerektirir:

POST /api/v1/webhooks HTTP/1.1
Host: api.nowtoprint.com
x-api-key: ntp_partner_v2_key_xxxxxxxxxxxxxxxxxxxx
Content-Type: application/json

Anahtar aktif ve süresi geçmemiş olmalı; tenant, organizasyon, principal, webhooks audience ve sabit webhooks.manage scope bağlarını taşımalıdır. Yalnızca formatı doğru olan anahtarlar kabul edilmez. Bu control-plane erişimi quote, order veya event delivery otomasyonunun public üretim trafiğinde genel olarak açık olduğu anlamına gelmez.

---

Operasyonel beklentiler

Konu	Rehber
Kapsam modeli	Anahtar yetenekleri ve limitleri entitlement, registry durumu ve rollout posture'a bağlıdır
Rotasyon	V2 key family içinde yeni anahtar çıkarın, tek sefer gösterilen secret'ı güvenli kanaldan iletin ve öncülü iptal edin
İdempotentlik	Yeniden denenebilecek metered read veya write işlemlerinde Idempotency-Key kullanın; eski client'lar için X-Idempotency-Key kabul edilir. Değer 160 karakteri geçmemeli
Loglama	İstek kimliklerini saklayın ve loglardan kimlik bilgilerini çıkarın
Webhook'lar	Webhook secret'larını API anahtarlarıyla aynı özenle koruyun; event delivery pilot/rollout kontrollü kalır

---

Yaygın kimlik doğrulama hataları

Durum	Anlam	Tipik çözüm
401	Eksik veya geçersiz kimlik bilgisi	Bearer header formatını ve doğru anahtar ailesini doğrulayın
403	Kapsam veya yetki uyumsuzluğu	Eksik onaylı capability'yi talep edin
429	Dağıtık kota tükendi	X-RateLimit-Reset sonrasını bekleyin
503	Credential/quota authority kapalı	Tekrar deneyin; sistem güvenli biçimde kapalı kalır

Credential V2 kotası Firestore transaction ile ayrılır ve aynı transaction içinde payload taşımayan kalıcı usage outbox kaydı oluşturulur. Kota veya audit deposu kullanılamıyorsa istek servis edilmez.

Partner kayıtları quota metadata decode eder; fakat bu snapshot consumption authority değildir. Transactional reservation port'u hash-only dönem sayaçları ve idempotent replay sağlar. Mevcut devre dışı Partner v1 capability'leri bu port'u çağırmadığı için quota 429 üretmez; enforcement ancak enabled capability port'u compose edip deployed evidence sağladığında launch iddiası olur.

---

Güvenlik kontrol listesi

• anahtarları sunucu taraflı secret storage içinde tutun
• anahtarları asla client-side JavaScript'e göndermeyin
• kimlik bilgilerini veya örnek live değerleri source control'e commit etmeyin
• loglarda, trace'lerde ve hata payload'larında auth header'larını redakte edin
• sandbox, pilot ve onaylı-live kimlik bilgilerini ayrı tutun
• bir rotanın public-current olduğunu varsaymadan önce /docs/api/openapi.yaml dosyasını yeniden kontrol edin

---

İlgili dokümanlar