API Kimlik Doğrulama

jekcms REST API'sinin sizden istediği tek şey var: bir başlıkta anahtar. OAuth el sıkışması yok, oturum çerezi yok, tazeleme akışı yok. n8n, Make ve Zapier bu dili zaten konuşuyor; sistem de bu yüzden böyle kuruldu.

API Anahtarları ekranı: üstte giden webhook'lar, altta uç adresleri — Tek ekranda iki yön: dışarı gönderdikleriniz, ve başkalarının çağırdığı adres.

Anahtarı gönderme

Üç başlık adı çalışır ve API üçünü de aynı görür. En yalını X-API-Key: ANAHTARINIZ. Otomasyon araçlarının çoğunun varsayılanı Authorization: Bearer ANAHTARINIZ. Yalnız Api-Key: ANAHTARINIZ gönderen birkaç istemci için üçüncüsü de kabul edilir.

Bir istek şöyle görünür:

curl -H "X-API-Key: ANAHTARINIZ" https://siteniz.com/api/v1/posts

Başarılı her yanıt aynı zarfla döner - bir success bayrağı ve içinde data:

{
    "success": true,
    "data": {
        "items": [],
        "total": 0,
        "pages": 0,
        "current_page": 1,
        "per_page": 20
    }
}

Hatalar da aynı zarfı kullanır; bayrak ters çevrilir ve kod nesnenin içinde bir kez daha tekrarlanır, böylece yalnız gövdeyi okuyan istemci de ne olduğunu anlar:

{
    "success": false,
    "error": { "code": 401, "message": "Unauthorized" }
}

Anahtar sorgu dizesinden okunmaz. Oraya yazmak onu yalnızca erişim kayıtlarına düşürür.

Anahtarlar nereden gelir

Yönetim → API Anahtarları ekranından; ekran yönetici girişi ister. Anahtara altı ay sonra da tanıyacağınız bir ad verin - n8n, zapier, mobil-test - ve isterseniz bir bitiş tarihi. Tarihi boş bırakırsanız anahtar siz iptal edene kadar yaşar.

Gizli değerin tamamı yalnızca onu üreten ekranda, bir kez görünür. jekcms yalnızca SHA-256 özetini saklar; yanında listede satırları ayırt edebilesiniz diye maskelenmiş bir parça (ilk sekiz, son dört karakter) durur. Değeri kaybederseniz geri getirilecek bir şey yok: yeni anahtar üretip eskisini pasife alın.

İptal anahtarı pasifleştirir ve bir sonraki istek başarısız olur - beklenecek bir önbellek yoktur. Liste ayrıca son kullanım zamanını gösterir; artık kimsenin kullanmadığı anahtarları bulmanın en hızlı yolu budur.

İzin modeli roldür

Kapsam (scope) diye bir şey yok. jekcms anahtarında posts:write bayrağı ya da anahtara özel izin listesi bulunmaz. Anahtar bir kullanıcı hesabıdır: onu oluşturan kişiye aittir ve o kişinin rolünün yapabildiği her şeyi yapar.

API Anahtarları ekranı yalnızca yöneticiye açık olduğu için, panelden üretilen her anahtar bir yöneticiye aittir ve yönetici yetkisi taşır. Bir API anahtarına veritabanı parolanız gibi davranın; her entegrasyona kendi anahtarını verin ki birini iptal etmek diğerlerini durdurmasın.

Yazma işlemleri config/constants.php içindeki ROLE_CAPABILITIES tanımına göre denetlenir:

| Rol | Anahtarın API üzerinden yapabildikleri | |---|---| | admin | Her şey; /users ve /settings dahil | | editor | Yazılar, sayfalar, medya, yorum moderasyonu, kategoriler ve etiketler | | author | Yazılar ve yüklemeler - yalnızca kendi yazıları | | subscriber | Yalnız okuma |

Gerekli yetkisi olmayan çağrı 403 ve Insufficient role for this operation ile döner. Başkasının yazısına uzanan bir yazar anahtarı 403 ve You can only modify your own content alır. Kategori, etiket ve yorum moderasyonu en az editör ister; /users ve /settings yöneticinin altındaki her role düz bir Forbidden döner.

Görmezden gelinecek tek kalıntı: api_tokens tablosundaki abilities sütunu eski bir tasarımdan kalmadır. API anahtarları için yazılır ama hiç okunmaz. Anlamı yalnızca giden webhook satırlarında vardır; orada abone olunan olay listesini tutar.

Hız sınırı

Sayaç anahtar başına değil, istemci IP'si başına çalışır: kayan 60 dakikalık pencerede API_RATE_LIMIT kadar istek, varsayılan 100. Sabit config/environment.php içinde tanımlıdır ve tanımlıysa API_RATE_LIMIT ortam değişkeninden okunur.

Sınır aşıldığında pencerenin en eski isteği düşene kadar her istek 429 ve Rate limit exceeded döner. Retry-After başlığı yok, X-RateLimit-* başlıkları yok, anahtar başına ayrı bütçe yok - aynı IP arkasındaki iki entegrasyon tek sayacı paylaşır. Yoğun bir akış işletiyorsanız duvara tekrar tekrar çarpmak yerine sabiti yükseltin.

Kimlik doğrulama sınırlayıcıdan sonra gelir; yani /api/v1/health bile bütçeden düşer ve her uç anahtar ister.

Anahtarın açtığı uçlar

Geçerli bir anahtara on üç uç yanıt verir: posts, media, categories, tags, comments, users, settings, webhook, trends, stats, sitemap, search ve health. webhook ucu, Otomasyon bölümünde anlatılan aksiyon tabanlı otomasyon yüzeyidir; diğerleri alışıldık REST kaynaklarıdır.

API ile oluşturulan yazılar doğrudan yazı tablosuna gider. API içerik kuyruğuna yazmaz - kuyruğa giden yolları İçerik Kuyruğu anlatıyor.

İşinizi kolaylaştıran alışkanlıklar

Her entegrasyona kendi adıyla anılan tek bir anahtar; böylece iptal etmek soruşturma değil karar olur. Taşerona ya da kısa ömürlü bir akışa verilen her anahtara bitiş tarihi. Gizli değer gerçek bir sır kasasında - n8n kimlik bilgileri, ortam değişkeni, parola yöneticisi - ve asla depoda değil. Bir de: biri ayrıldığında ya da bir sır sızdığında iptal aynı saat içinde yapılır, aynı çeyrek içinde değil.