API Kimlik Doğrulama

jekcms REST API'si token ile doğrular: bir başlıkta gönderilen, uzun ömürlü tek bir sır. OAuth turu yok, oturum çerezi yok. n8n, Make, Zapier ve çoğu otomasyon platformunun beklediği yöntem budur; API'nin istediği de yalnızca budur.

Bu sayfa API'nin gerçekte ne yaptığını anlatır. Bir özellik yoksa, yok diye yazar.

Token nasıl gönderilir

İki başlık kabul edilir, ikisi denktir:

X-API-Key: TOKENINIZ

Authorization: Bearer TOKENINIZ

En sade istek:

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

Eksik veya tanınmayan token 401 döner:

{ "success": false, "error": "Unauthorized" }

Token'ı sorgu dizesine koymayın — API oradan okumaz, üstelik sorgu dizeleri erişim kayıtlarına düşer.

Token nereden gelir

Yönetim panelinde API Anahtarları. Bir token oluşturun, sonradan tanıyacağınız bir ad verin (n8n, zapier, mobil-test) ve isterseniz bir son kullanma tarihi belirleyin.

Token'ın tamamı yalnızca bir kez, oluşturulduğu anda gösterilir. jekcms yalnızca SHA-256 özetini saklar; bu yüzden size bir daha gösteremez. Kaybederseniz yenisini üretip eskisini pasife alın.

Her token satırı şunları taşır:

kullanıcı — token'ın adına hareket ettiği hesap. Asıl önemli alan budur; bir sonraki bölüme bakın.
ad — sizin etiketiniz.
aktiflik — pasife almak = iptal etmek. İlk istekten itibaren geçerlidir; beklenecek bir önbellek yoktur.
son kullanma — isteğe bağlı. Tarih geçtiğinde token artık doğrulanmaz (401). Boşsa süresizdir.
son kullanım zamanı — her başarılı istekte güncellenir; böylece artık kimsenin kullanmadığı token'ları görürsünüz.

Yetkilendirme nasıl çalışır — kapsam değil, ROL

Çoğu API dokümanının yanlış anlattığı kısım burası; bir kez okuyun.

jekcms token'ının kapsamı (scope) yoktur. posts:write diye bir şey yoktur, token başına izin listesi yoktur. Token bir hesaptır: bir kullanıcıya aittir ve tam olarak o kullanıcının rolünün yapabildiklerini yapabilir.

Yazma işlemleri, rolün yeteneklerine göre denetlenir (config/constants.php içindeki ROLE_CAPABILITIES):

| Rol | API üzerinden yapabildikleri | |---|---| | admin | her şey: yazı, sayfa, medya, kullanıcı, ayar, otomasyon | | editor | yazı, sayfa, medya, yorum, kategori — kullanıcı ve ayar hariç | | author | yalnızca kendi yazıları ve yüklemeleri — başka yazarın içeriğine yazma reddedilir (403) | | subscriber | yalnızca okuma |

Gerekli yetkisi olmayan çağrı HTTP 403 alır:

{ "success": false, "error": "Insufficient role for this operation" }

Pratik sonuç: en az yetki ilkesi, kutucuk işaretleyerek değil, doğru kullanıcıyı seçerek uygulanır. n8n akışınızın tek işi yazı yayımlamak ve görsel yüklemekse, bunun için ayrı bir editor (ya da author) hesabı açın ve token'ı o hesaptan üretin. Ekranda en kolayı o diye otomasyona admin token'ı vermeyin.

api_tokens tablosunda eski bir tasarımdan kalma abilities kolonu vardır. Uygulanmaz. Ona güvenmeyin; erişimi rol belirler.

Hız sınırı

Sınır istemci IP'si başına uygulanır, token başına değil: saatte API_RATE_LIMIT istek, varsayılan 100. config/constants.php içinde tanımlıdır ve API_RATE_LIMIT ortam değişkeniyle değiştirilebilir.

Sınır aşıldığında:

HTTP/1.1 429 Too Many Requests

{ "success": false, "error": "Rate limit exceeded" }

Retry-After başlığı yoktur, token başına ayrı kova da yoktur. Yoğun bir entegrasyon çalıştırıyorsanız körlemesine yeniden denemek yerine ortamınızda API_RATE_LIMIT değerini yükseltin. /api/v1/health dâhil her uç sınırlayıcıdan geçer ve token ister.

Token'ın açtığı uçlar

posts, media, categories, tags, comments, users, settings, trends, stats, sitemap, search, health ve webhook (n8n'in kullandığı, aksiyon tabanlı otomasyon yüzeyi).

API yazı oluşturur ve günceller. İçerik kuyruğuna yazmaz — gerçek giriş yolları için İçerik Kuyruğu sayfasına bakın.

Makul alışkanlıklar

Her entegrasyona bir token, adı da entegrasyonun adı olsun. İptal etmek böylece netleşir, etki alanı küçülür.
Token'ı, işi gören en küçük role sahip hesaptan üretin.
Yükleniciye ya da kısa ömürlü bir hatta verilen token'a son kullanma tarihi koyun.
Sırrı gerçek bir sır yöneticisinde saklayın (n8n kimlik bilgileri, ortam değişkeni, parola yöneticisi) — Git'te asla.
Biri ayrıldığında ya da bir sır sızdığında token'ı derhâl pasife alın.