API Kimlik Doğrulama ve Bearer Token'lar

Kimlik Doğrulama Nasıl Çalışır

1. Quote3D hesabınıza kaydolun ve giriş yapın.
2. Dashboard panelinizdeki "Token'lar" sekmesinden bir API token'ı oluşturun.
3. Token'ı API isteklerinize ekleyin. Authorization: Bearer desteklenir ve X-API-Token da kabul edilir:
   Authorization: Bearer YOUR_TOKEN_HERE
4. Sunucu token'ınızı doğrular ve geçerli ve süresi dolmamışsa erişim sağlar.

Token Kapsamları

Bir token'ın kapsamı, hangi uç noktalara ulaşabileceğini belirler. Kapsamı token'ı oluştururken seçersiniz ve panelinizin Token'lar sayfasında görebilirsiniz.

• Tam erişim — sunucu tarafı bir token için varsayılan. Planınızın izin verdiği her uç noktaya ulaşır.
• Widget — bir mağazaya gömdüğünüz token için kullanılacak kapsam. Gömülebilir widget'ın ihtiyaç duyduğu şeylerle sınırlıdır ve webhook'lara, hesap bilgilerine, analitiğe, kullanıma veya kotaya ulaşamaz.

Token'ın kapsamı dışındaki bir uç noktaya yapılan çağrı, token geçerli olsa bile 403 ile reddedilir. Aynı token başka yerlerde çalışırken bir istek 403 ile başarısız oluyorsa, her şeyden önce kapsamını kontrol edin.

Token Yaşam Döngüsü

• Bir token'ın değeri yalnızca bir kez, oluşturulurken gösterilir. Sonrasında geri alınamaz — hemen gizli anahtar yöneticinize kaydedin. Kaybederseniz yeni bir değer almak için token'ı döndürün.
• Token'lar son kullanma tarihiyle oluşturulabilir. Süresi dolmuş bir token çalışmayı durdurur ve 401 döndürür; panel her token'ın son kullanma tarihini gösterir.
• Bir token'ı döndürmek yeni bir değer üretir ve eskisini hemen geçersiz kılar. Yeni değeri döndürmeden önce dağıtın, çünkü eski token'ı kullanan devam eden istekler anında başarısız olmaya başlar.
• Bir token belirli IP adresleriyle sınırlandırılabilir. Başka herhangi bir adresten gelen çağrılar 403 ile reddedilir — sunucu taşıdıktan veya bir NAT ağ geçidini değiştirdikten sonra sık karşılaşılan bir sürpriz.
• Planınız kaç token tutabileceğinizi sınırlar. Ücretsiz planlar bir sunucu token'ı ve bir widget token'ı sağlar.

Kimlik Doğrulama Başarısız Olduğunda

Reddedilen bir istek, success: false ve kısa bir mesajla standart hata zarfını döndürür. Yeniden yazılabilecek mesaj metnine değil, HTTP durum koduna göre dallanın.

{
  "success": false,
  "error": "API token has expired"
}

• 401 — token eksik, hatalı biçimlendirilmiş, süresi dolmuş veya iptal edilmiş. Başlık adını ve kopyalanırken değerin kırpılmadığını kontrol edin.
• 403 — token geçerli ancak bu çağrı için izinli değil. Olağan nedenler bir kapsam kısıtlaması ya da çağıranı içermeyen bir IP izin listesidir.

Token Formatı

Quote3D token'ları bearer-style API kimlik bilgileridir. İstemciler bunları opak sırlar olarak ele almalı ve token'ın iç yapısına bağımlı olmamalıdır.

Bir JWT üç bölümden oluşur:

1. Header: İmzalama algoritmasını ve token türünü belirtir.
2. Payload: Kullanıcı verilerini ve talepleri içerir (kullanıcı ID'si, e-posta ve sona erme süresi gibi).
3. Signature: Token'ın değiştirilmediğini doğrular.

Bir token şöyle görünebilir:

Entegrasyonlar için önemli kural basittir: token'ı güvenli bir şekilde saklayın, her istekte gönderin ve entegrasyon açıkça istemci tarafında bir token gerektirmiyorsa, istemci kodunda ayrıştırmaktan veya açığa çıkarmaktan kaçının.

Örnek: Token'ınızı Kullanma

Token'ınızı curl ile şu şekilde kullanabilirsiniz. Tek bir authentication header stilini tutarlı şekilde kullanın:

Veya API Playground'da, oturumunuzu kimlik doğrulamak için token'ınızı yetkilendirme modalına (kilit simgesi) yapıştırın. İsterseniz özel entegrasyonlarda X-API-Token başlığını da kullanabilirsiniz.