Kimlik Doğrulama ve Kapsamlar
Her public API isteği uzun ömürlü bir API anahtarını bearer token olarak taşımalıdır. Kapsamlar her anahtarın neye izinli olduğunu sınırlar — yalnızca entegrasyonunuzun gerçekten ihtiyaç duyduğu yetkileri verin.
Bearer token formatı
API anahtarları şöyle görünür:
scs_live_t9JQ10cDjddmslzv9mRKYqaDS5ZU1KuDHscs_live_ öneki, anahtarın SecureCodingHub için bir prodüksiyon kimlik bilgisi olduğunu belirtir. Token'lar toplam 41 karakterdir (9 karakterlik önek + 32 karakterlik rastgele gövde). Anahtar oluşturulduğunda tam olarak bir kez döndürülürler.
Token'ı her istekte standart bir Bearer kimlik doğrulama header'ı olarak gönderin:
Authorization: Bearer scs_live_t9JQ10cDjddmslzv9mRKYqaDS5ZU1KuDHAPI anahtarı oluşturma
API anahtarları API üzerinden değil, admin konsolunda oluşturulur.
Kurum admin'i olarak app.securecodinghub.com üzerinde oturum açın.
Kenar çubuğundan Organization → API Keys sayfasını açın.
+ Create new key düğmesine tıklayın. Anahtara açıklayıcı bir ad verin (örn. GitHub Actions — CI veya Looker BI senkronizasyonu).
Yalnızca entegrasyonun ihtiyaç duyduğu kapsamları işaretleyin. Salt okunur kapsamlar mavi, yazma kapsamları kehribar renginde vurgulanır.
(İsteğe bağlı) Son kullanma tarihi belirleyin. Son kullanma tarihi olmayan anahtarlar siz iptal edene kadar geçerli kalır.
Create key düğmesine tıklayın. Tam token bir modal içinde gösterilir. Şimdi secrets manager'ınıza kopyalayın. Bunu tekrar görüntüleyemeyeceksiniz — yalnızca önek ve son dört karakter saklanır.
Kapsam referansı
SecureCodingHub okuma ve yazma katmanlarına ayrılmış 16 ince granül kapsam kullanır. Eşleşen kapsam olmadan bir uç noktaya gelen istek, yanıt gövdesi {"error":"insufficient_scope","required":"…","present":[…]} ile birlikte 403 Forbidden döner.
| Kapsam | Kaynak | Katman | Yetkiler |
|---|---|---|---|
org:read | Kurum | Okuma | Kurum meta verisini okur (ad, plan, koltuk sayısı). |
users:read | Kullanıcılar | Okuma | Kullanıcıları listeler; kullanıcı detayını alır. |
users:write | Kullanıcılar | Yazma | Kullanıcı oluşturur, günceller, deaktive eder. |
teams:read | Ekipler | Okuma | Ekipleri ve üyeleri listeler. |
teams:write | Ekipler | Yazma | Ekip oluşturur, günceller, siler. |
assignments:read | Atamalar | Okuma | Atamaları listeler; tamamlanma ile birlikte detay alır. |
assignments:write | Atamalar | Yazma | Atama oluşturur, günceller, deaktive eder. |
custom-courses:read | Özel Kurslar | Okuma | Özel kursları öğeleriyle birlikte listeler. |
custom-courses:write | Özel Kurslar | Yazma | Özel kurs oluşturur, günceller, siler. |
progress:read | İlerleme | Okuma | Kullanıcı başına pratik ve öğrenme ilerlemesi. |
certificates:read | Sertifikalar | Okuma | Sertifikaları listeler ve indirir. |
audit-log:read | Denetim Günlüğü | Okuma | Denetim günlüğü girdilerini listeler. |
compliance:read | Uyumluluk | Okuma | Uyumluluk gösterge paneli verileri. |
content:read | İçerik | Okuma | Konular, senaryolar, CWE-konu eşlemesi. |
sarif:ingest | SARIF | Yazma | SARIF çalıştırmalarını içeri alır ve eğitim otomatik atar. |
webhook:manage | Webhook'lar | Yazma | Giden webhook uç noktalarını yönetir. |
Önerilen kapsam setleri
| Kullanım senaryosu | Minimum kapsamlar |
|---|---|
| CI/CD SARIF içeri alımı | sarif:ingest |
| İK destekli kullanıcı sağlama | users:write, teams:write |
| BI / raporlama dışa aktarımı | users:read, progress:read, assignments:read, audit-log:read |
| Ticketing ve SOAR (olay aboneleri) | webhook:manage, assignments:read |
| Denetçi için salt okunur dışa aktarım | org:read, audit-log:read, compliance:read, certificates:read |
Rotasyon ve iptal
Bir anahtarı döndürmek için önce yeni bir anahtar oluşturun, yeni token'ı dağıtın, ardından Organization → API Keys altında eski olanı iptal edin. İptal anında etki eder — eski token'ı kullanan uçuştaki istekler saniyeler içinde 401 Unauthorized dönmeye başlar.
Bir anahtar sızdırılırsa iptal edin. "Duraklat" durumu yoktur; iptal kalıcıdır. Token yeniden etkinleştirilemez.
Saklama en iyi uygulamaları
- Token'a veritabanı şifresi gibi davranın. Asla kaynak kontrolüne commit etmeyin.
- Platformunuzun yerel secret deposunu tercih edin (AWS Secrets Manager, GCP Secret Manager, GitHub Actions secrets, Vault, 1Password Connect).
- CI'da, token'ı yalnızca ihtiyaç duyan adıma enjekte edin;
echoile yazdırmaktan kaçının. - Bağımsız iptal edebilmek için her entegrasyona bir anahtar verin. Tek bir anahtarı CI, BI ve SOAR arasında paylaştırmayın.
- Kısa ömürlü entegrasyonlar (PoC, satıcı değerlendirmeleri) için oluşturulan token'lara son kullanma tarihi koyun.
Yaygın hatalar
| Durum | Yanıt | Anlam |
|---|---|---|
401 | {"error":"unauthorized"} | Eksik, hatalı biçimlendirilmiş, iptal edilmiş veya süresi dolmuş token. |
403 | {"error":"insufficient_scope",…} | Token geçerli ancak bu uç nokta için gerekli kapsam yok. |
429 | {"error":"rate_limited"} | Dakika veya saat başına üst sınıra ulaşıldı. Bkz. Hız Limitleri. |