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
Sandbox	ntp_test_*	Geliştirme, QA ve onaylı entegrasyon testleri
Live	ntp_live_*	Yalnızca seçili onaylı akışlar; genel public GA anahtarı değildir

---

İ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_live_xxxxxxxxxxxxxxxxxxxx
Content-Type: application/json

Anahtar registry'de aktif, organizasyon kapsamlı ve webhooks:manage iznine sahip olmalı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	Anahtarları düzenli aralıklarla ve açığa çıkma durumunda derhal rotasyona alın
İ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	Limit veya rollout tavanı dolu	Geri çekilin ve Retry-After ile yanıt başlıklarına güvenin

---

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