Kimlik doğrulama

API, sunucuların kimliğini kuruluş API anahtarlarıyla doğrular. Bir anahtar bir kuruluşa aittir (bir kişiye değil), bir dizi izin taşır ve tam olarak tek bir modda çalışır: test veya canlı.

Anahtarı gönderme

İki başlıktan birini kullanın:

# Authorization header (recommended)
curl https://api.bonafidesign.com/v1/envelopes -H "Authorization: Bearer bf_live_…"

# or x-api-key
curl https://api.bonafidesign.com/v1/envelopes -H "x-api-key: bf_live_…"

Anahtarlar bf_live_… veya bf_test_… biçimindedir. Eksik anahtar 401 (unauthorized) döndürür; hatalı biçimlendirilmiş, iptal edilmiş veya süresi dolmuş bir anahtar da 401 döndürür. Anahtarları sunucunuzda tutun: asla bir tarayıcıya veya mobil uygulamaya göndermeyin. Tarayıcıda imzalama için bunun yerine bir imzalama oturumu oluşturun.

Test ve canlı anahtarlar

	Test (`bf_test_…`)	Canlı (`bf_live_…`)
Belgeler	`TEST` filigranıyla oluşturulur	Filigransız
E-posta	Yalnızca kuruluşunuzun üyelerine teslim edilir	Her alıcıya teslim edilir
Faturalandırma	Ücretsiz ve sınırsız, hiçbir zaman sayılmaz	Tamamlanan zarflar planınızdan düşülür
Veriler	Anahtarla oluşturulan zarflar, bağlantılar ve webhook uç noktaları test modundadır	Canlı mod

Mod her zaman anahtardan gelir, asla istekten gelmez: POST /v1/envelopes üzerindeki ?test_mode=true yalnızca panel oturumları için geçerlidir. Listeler (GET /v1/envelopes, GET /v1/signing-links) yalnızca anahtarın modundaki kayıtları döndürür ve bir zarfın olayları yalnızca aynı moddaki webhook uç noktalarına gider. Her zarf ve webhook yükü hangi modda olduğunu belirtir (testMode).

Anahtar oluşturma ve iptal etme

Anahtarlar panelde, Ayarlar › API anahtarları bölümünde, apikey:manage iznine sahip üyeler (sahipler ve yöneticiler) tarafından yönetilir. Sır, anahtar oluşturulurken yalnızca bir kez gösterilir. Bir anahtara ad, mod, son kullanma süresi (1 ila 365 gün veya hiç) ve kapsamlar verebilirsiniz.

Kapsamlar

Bir anahtarın kapsamları, kullanabileceği kuruluş izinleridir. Varsayılan olarak yeni bir anahtar, oluşturan kişinin izinlerinden yönetimsel olanlar (org:manage, member:manage, sso:manage, apikey:manage, billing:manage) çıkarılmış hâlini alır ve kimse bir anahtara kendisinde olmayan bir izni veremez. Anahtarın kapsamı dışındaki bir çağrı, eksik izni belirten bir 403 döndürür:

{
  "type": "https://bonafidesign.com/problems/forbidden",
  "title": "Forbidden",
  "status": 403,
  "detail": "Missing permission: envelope:send.",
  "requestId": "req_V1StGXR8Z5jdHi6BmyT2"
}

İzin	Anahtarın yapabildikleri
`template:read`	Şablonları, sürümleri ve bunların PDF’lerini listeleme ve okuma
`template:write`	Şablon oluşturma, dosya yükleme, taslak kaydetme, kullanılmayan şablonları silme
`template:publish`	Bir taslağı yeni sürüm olarak yayımlama
`envelope:read`	Zarfları, belgeleri ve denetim kayıtlarını listeleme ve okuma; imzalama bağlantılarını listeleme
`envelope:send`	Zarf, imzalama oturumu ve imzalama bağlantısı oluşturma; bağlantıları yeniden gönderme
`envelope:void`	Devam eden zarfları iptal etme
`org:manage`	Webhook uç noktalarını yönetme ve olayları yeniden teslim etme; kuruluş ayarlarını okuma
`billing:manage`	Kullanımı (`GET /v1/usage`) ve fatura tutarlarını okuma

Webhook uç noktalarını yönetmek, anahtarlara varsayılan olarak verilmeyen org:manage iznini gerektirir: uç noktaları panelde kaydedin veya bu kapsamı açıkça içeren bir anahtar oluşturun.

Hangi uç nokta neyi kabul eder

API referansındaki her işlem kendi güvenlik şemalarını listeler. Kısaca:

API anahtarı veya panel oturumu: şablonlar, zarflar, imzalama oturumları, imzalama bağlantıları, webhook uç noktaları, kuruluş ayarları, faturalandırma özeti ve kullanım.
Yalnızca panel oturumu: API anahtarları, SCIM belirteçleri, SSO bağlantı ayarları, kuruluş logosu yükleme, faturalandırma ödeme ve portal sayfaları, bir webhook sırrını görüntüleme.
İmzacı belirteci: barındırılan sayfa ve <bf-signing> tarafından bir oturum belirteci (bfs_…) veya onun karşılığında alınan erişim belirteci (bfa_…) ile kullanılan /v1/signing/*.
Herkese açık: /v1/links/{id} (kalıcı bağlantılar), /v1/sso/discover ve doğrulama API’si (/v1/public/*, /.well-known/bona-fide/keys.json).

Panele giriş yapma

Kişiler (sunucular değil) panele https://app.bonafidesign.com/sign-in adresinden giriş yapar. Varsayılan yöntem e-posta ve paroladır; alternatifler e-postayla gönderilen altı haneli bir kod (Bunun yerine bana e-postayla kod gönder), sihirli bağlantı, geçiş anahtarı, Google veya Microsoft ve şirketinizin SSO’sudur.

Parolayla hesap oluşturmak tek bir e-posta gönderir: adresin size ait olduğunu onaylayan bir kod. Bu onaya kadar parola ile giriş yapılamaz. Zaten hesabı olan bir adresle kaydolmak hiçbir şeyi değiştirmez ve yeni bir kayıtla tamamen aynı yanıtı verir; adresin sahibine bunun yerine nasıl giriş yapacağını açıklayan bir e-posta gönderilir.
Parolalar 12 ila 128 karakter uzunluğundadır ve tuzlanmış scrypt hash’leri olarak saklanır. Bilinen bir veri ihlalinde yer alan yeni bir parola reddedilir: parolanın kendisi asla değil, yalnızca SHA-1 hash’inin ilk beş karakteri Have I Been Pwned hizmetine gönderilir (k-anonimlik). Bu hizmet iki saniye içinde yanıt vermezse parola kontrol yapılmadan kabul edilir.
Parolanızı mı unuttunuz? Sıfırlama e-postası, yeni bir parola seçeceğiniz bir sayfaya bağlantı verir. Bağlantı bir kez çalışır, bir saat sonra geçerliliğini yitirir ve kullanıldığında tüm cihazlarda oturumunuz kapatılır.
Henüz parolanız yok mu? Kodla, bağlantıyla, geçiş anahtarıyla veya Google / Microsoft ile oluşturulan hesaplar bu şekilde giriş yapmaya devam eder ve Ayarlar › Hesap bölümünden parola ekleyebilir. İlk parolayı belirlemek son 15 dakika içinde yapılmış bir giriş gerektirir (sayfa, siz olduğunuzu onaylamak için e-postayla bir kod gönderir); parolayı değiştirmek mevcut parolayı gerektirir. Her iki işlem de diğer oturumlarınızı kapatır.
Hatalar hesapları asla açığa çıkarmaz: yanlış parola, bilinmeyen adres ve parolası olmayan hesap aynı yanıtı alır; sıfırlama isteği ise her zaman e-postanın yolda olduğunu söyler.
Hız limitleri: parolayla giriş, kayıt ve sıfırlama istekleri IP adresi ve e-posta adresi başına sınırlıdır; limit aşıldığında süre penceresi geçene kadar yanıt 429 olur.
Şirket SSO’su: kuruluşunuz SSO’yu zorunlu kıldığında, kuruluşun e-posta alan adlarındaki üyeler yalnızca kimlik sağlayıcı üzerinden giriş yapar. Onlar için parolalar, kodlar ve sihirli bağlantılar reddedilir; sahipler acil durum girişi olarak e-posta kodunu kullanmaya devam eder.

İstek kimlikleri

Her yanıt bir x-request-id başlığı, her hata gövdesi de bir requestId taşır. Günlükleri ilişkilendirmek için kendi x-request-id değerinizi (A-Z a-z 0-9 . _ - karakterlerinden 8 ila 128 karakter) gönderebilirsiniz; aksi hâlde API bir tane üretir. Destekle iletişime geçtiğinizde bu kimliği belirtin.