Kimlik Doğrulama

Güncel RFQ oluşturma ve kuruluşa ait tekil RFQ/teklif okuma sözleşmesi /api/v1/marketplace/openapi.json adresinde üretilir. Eski /docs/api/openapi.yaml yayını farklı bir referanstır; iki belgenin eşit olduğunu varsaymayın. Ortam adresini ve etkin yetkileri onboarding sırasında doğrulayın.

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_partner_v2_<issued-key-id>_<secret>
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_<issued-key-id>_<secret>
Content-Type: application/json

Anahtar aktif ve süresi geçmemiş olmalı; organizasyon, principal ve izinli tedarikçi kimlikleri, 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	RFQ kimliği ayrıştırılmış gövdeden sunucuda türetilir; diğer rotaların tekrar sözleşmesini ayrı okuyun
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	Organizasyon kabiliyeti reddi	Eksik onaylı capability'yi talep edin
429	Dağıtık kota tükendi	Problem gövdesindeki resetAt zamanını kullanın
503	Credential/quota authority kapalı	Tekrar deneyin; sistem güvenli biçimde kapalı kalır

Kimliği doğrulanan her Partner v1 isteği, daha sonra kapalı estimate/order sınırına ulaşsa da Credential V2 fixed-window kotasını tüketir (varsayılan kimlik bilgisi/organizasyon/scope başına dakikada 120). Bucket ile payload içermeyen usage outbox aynı Firestore transaction’ındadır; otoriteye erişilemiyorsa kapalı kalır.

RFQ oluşturma, katalog bağlamı ve L2 çözümünden sonra ayrıca ticari günlük hakkı rezerve eder. Aynı gövde rezervasyonu günlük sayacı tekrar tüketmeden oynatılır. Bu, kimlik istek kotasından ayrıdır: yeniden denemeler istek olarak sayılmaya devam eder. Yanlış scope dahil kimlik reddi 401; organizasyon kabiliyeti reddi 403 olabilir. Credential 429 Problem Details gövdesinde resetAt taşır; her Partner rotasının X-RateLimit veya Retry-After başlığı verdiğini varsaymayın.

Partner RFQ oluşturma güncel işlem kimliğini parse edilmiş gövdeden türetir. İstemcinin Idempotency-Key başlığı bu kimliği seçmez. Diğer yüzeylerin kuralı farklıdır: PDF partner attach isteğe bağlı anahtar destekler; metered data-product sözleşmeleri ayrıdır ve dış erişime kapalı kalır.

Kimlik üretimi policy id’leri, organizasyon/tedarikçi bağları, ticari tier ve en fazla 90 gün ömür taşıyan yetkili operatör akışıdır. Secret yalnız bir kez döner ve saklanan idempotent replay’den çıkarılır; güvenli teslimat kullanın ve değiştirilen kimliği iptal edin. Partner dashboard çalışan bir self-servis anahtar üreticisi değildir.

---

Kaynak zinciri: consumeCredentialQuota dakika sayacı ile credential_v2_usage_outbox kaydını aynı Firestore transaction içinde yazar; ret PARTNER_API_RATE_LIMITED olur. Günlük RFQ reservation port ise katalog/L2 kontrolünden sonra çağrılır. Disabled Partner v1 estimate/order adaptörleri günlük RFQ rezervasyonu yapmaz, ancak önce kimlik dakika kotasını tüketir.

Günlük rezervasyon reddi PARTNER_RFQ_QUOTA_EXCEEDED kodlu 429 döndürür; dakika kotası reddinden ayrı quotaKind, limit, remaining, resetAt alanlarını işleyin.

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