API sürümleme ve kullanımdan kaldırma politikası

Bu sayfa KeenAuth'un API'lerini nasıl sürümlediğini, bir kaldırmanın nasıl duyurulduğunu ve SDK'ların, CLI'ın, Terraform/OpenTofu sağlayıcısının ve MCP sunucusunun ne kadar süre güvenlik düzeltmesi aldığını anlatır. Her duyuru değişiklik günlüğünde yayımlanır.

API sürümleri

Yönetim API'si ana sürümünü yolda taşır (/v1). v1 içinde yalnız eklemeli değişiklik yapılır:

• yeni bir uç nokta;
• yeni bir isteğe bağlı istek alanı;
• yeni bir yanıt alanı;
• yeni bir enum değeri;
• yeni bir hata kodu;
• yeni bir olay türü.

Entegrasyonunuzu bu eklemeleri kabul edecek biçimde yazın.

Kırıcı değişiklik yalnız yeni bir ana sürümle (/v2) yapılır. Kırıcı değişiklikler şunlardır: bir alanı kaldırmak ya da yeniden adlandırmak, bir tipi değiştirmek, zorunlu alan eklemek, varsayılan davranışı değiştirmek ve sayfalamayı, sıralamayı ya da varsayılan limit değerini değiştirmek. v1, v2 genel kullanıma açıldıktan sonra en az 24 ay kullanılabilir kalır.

KeenAuth tarih tabanlı sürüm başlıkları kullanmaz; yoldaki ana sürüm ve yalnız eklemeli değişiklik kuralı sözleşmenin tamamıdır.

Beta ve GA işlemleri

OpenAPI belgesinde her işlem x-idp-stability: beta ya da x-idp-stability: ga olarak işaretlidir. beta bir işlem özel ya da herkese açık beta sırasında değişebilir ve aşağıdaki kullanımdan kaldırma kurallarına tabi değildir; yanıtları Idp-Stability: beta başlığını taşır. ga bir işlem dondurulmuştur: yalnız bu sayfadaki kurallarla değişir.

Olaylar ve token claim'leri

• Müşteri olay türleri bir şema sürümü (v<n>) taşır. Yükte kırıcı bir değişiklik yeni bir şema sürümü açar; iki sürüm 365 gün paralel teslim edilir ve her web kancası uç noktası alacağı sürümü seçer.
• Token'a claim eklemek eklemeli bir değişikliktir. Bir claim'i kaldırmak ya da anlamını değiştirmek 365 gün önceden duyurulur ve discovery belgesindeki claims_supported güncellenir.

Kullanımdan kaldırma ve kaldırma

Bir uç noktanın, parametrenin, claim'in, scope'un, olay türünün, imza algoritmasının ya da başka bir yüzeyin kaldırılması, kaldırma tarihinden en az 365 gün önce değişiklik günlüğünde duyurulur. Her kullanımdan kaldırmanın dep-<YYYY>-<NN> biçiminde bir kimliği, bir kullanımdan kaldırma tarihi, bir kaldırma (sunset) tarihi, varsa yerine geçen bir öğesi ve bir taşıma rehberi vardır.

Güvenlik istisnası: bir güvenlik açığını kapatmak için v1 içindeki davranış 365 günlük duyuru olmadan değişebilir. Böyle bir değişiklik değişiklik günlüğünde security etiketiyle yayımlanır ve etkilenen ortamlara e-postayla bildirilir.

API yanıtlarındaki sinyaller

Kaldırılmakta olan bir işlemin yanıtı şunları taşır:

• Deprecation: @<unix_epoch>: RFC 9745 yapılandırılmış tarihi olarak kullanımdan kaldırma tarihi;
• Sunset: <IMF-fixdate>: kaldırma tarihi (RFC 8594);
• Link: <doc_url>; rel="deprecation" ve Link: <doc_url>; rel="sunset": taşıma rehberi.

Kaldırma tarihinden sonra işlem endpoint_sunset problem koduyla 410 döner. OAuth ve OpenID Connect protokol kaldırmaları (bir imza algoritması, bir client kimlik doğrulama yöntemi, bir parametre) başlık taşıyamaz; bunlar client başına sayılır ve aynı bildirimlerden geçer.

Kullanımınızı nerede görürsünüz

• Ortam logu: saatte en çok bir kez, deprecation_id, client_id ve sunset_at içeren bir deprecation_notice kaydı.
• Pano: Kullanımdan kaldırmalar sayfası son 30 günü kullanımdan kaldırma, client ve SDK sürümüne göre gösterir; kaldırma tarihinden 90 gün önce itibaren bir afiş görünür.
• API: GET /v1/reports/deprecation-usage?from=&to= (izin reports:read).
• E-posta: hesabın owner ve admin rollerine ve ortamın teknik kontağına; duyuru günü (yüzeyi kullanan her ortam) ve kaldırma tarihinden 180, 90, 30 ve 7 gün önce (son 30 günde kullanan ortamlar).

Resmi SDK'lar, CLI, sağlayıcı ve MCP sunucusu her istekle Idp-Client: <paket>/<sürüm> (<çalışma_zamanı>/<sürüm>) gönderir. Başlık kimlik doğrulama değildir; yalnız sayım için kullanılır ve biçim dışı değer yok sayılır. Kullanım sayıları IP adresi, User-Agent ya da son kullanıcı kimliği saklamaz.

SDK ve araç destek politikası

SDK'lar, CLI, Terraform/OpenTofu sağlayıcısı ve MCP sunucusu anlamsal sürümleme (semver) izler. Ana sürüm yalnız dilin kendisindeki kırıcı bir değişiklikle ya da API'nin yeni bir ana sürümüyle artar.

• Ürün hattı bir bütün olarak, genel kullanıma açılışından itibaren en az 5 yıl güvenlik desteği alır.
• Güvenlik düzeltmeleri her paketin en güncel ana sürümünde yayımlanır ve ona yükseltmek ücretsizdir.
• Bir önceki ana sürüm, yeni ana sürüm genel kullanıma açıldıktan sonra 12 ay güvenlik ve kritik hata düzeltmesi alır; sonra destek süresi biter.
• Yayımlanan her güvenlik güncellemesi en az 10 yıl ya da daha uzunsa destek süresinin kalanı boyunca erişilebilir kalır.
• Destek bitişinden 90 gün önce itibaren SDK, sunucunun Deprecation başlığını ve kendi destek bitiş tarihini uygulamanızın loguna uyarı olarak yazar.
• Desteği biten SDK sürümleri sunucuda engellenmez; pano ve e-posta sizi uyarır.
• Destek bitişi değişiklik günlüğünde ve paket kayıt defterinde duyurulur (npm deprecate; PyPI'da açıklama, sürüm geri çekilmez).

Çalışma ortamı desteği

SDK'lar, üreticisinin hâlâ güvenlik düzeltmesiyle desteklediği çalışma ortamı sürümlerini destekler: Node.js LTS, üst kaynağın destek takvimine göre Python, Go'nun son iki sürümü, Java 17 ve 21, .NET LTS, PHP 8.2 ve sonrası, Ruby 3.2 ve sonrası, iOS 16 ve sonrası, Android API 26 ve sonrası. Asgari çalışma ortamı matrisi her ana sürümle yayımlanır. Üreticisinin desteğini yitiren bir çalışma ortamı bir minor sürümle bırakılır ve bu, değişiklik günlüğünde 90 gün önceden duyurulur.