API Kimlik Doğrulama

jekcms'in REST API'sini kullanmak için bir Bearer token'a ihtiyacınız var. Bu, her istekte yolladığınız uzun bir gizli anahtar — OAuth döngüsü, oturum çerezi, CSRF token'ı yok. Sunucudan sunucuya entegrasyonlar için en basit yöntem ve n8n, Make, Zapier gibi platformların beklediği de tam olarak bu.

Diyelim ki bir n8n akışınız var ve sitede yeni yazı oluşturacak. Önce jekcms'te bir token üretiyorsunuz, n8n'e yapıştırıyorsunuz, iş tamam. Bu sayfa token'ı nasıl üreteceğinizi, hangi yetkileri vereceğinizi, nasıl iptal edeceğinizi ve hız sınırlarını anlatıyor.

Bearer başlığı nasıl görünür?

Her kimlik doğrulanmış istek şu başlığı taşır:

Authorization: Bearer YOUR_TOKEN

En basit örnek:

curl -H "Authorization: Bearer YOUR_TOKEN" https://yoursite.com/api/v1/posts

Başlık eksikse ya da yanlışsa şu cevap döner:

{ "error": "unauthorized", "message": "missing or invalid bearer token" }

Token'ı URL'nin sorgu dizisine (query string) koymayın. Sorgu dizileri sunucu erişim loglarına, proxy loglarına, tarayıcı geçmişine düşer; başlıklar düşmez.

Token nasıl üretilir?

Admin → Settings → API Tokens → Create new token.

Doldurun:

Name — sadece sizin için bir etiket. Sonradan iptal etmesi kolay olsun diye entegrasyonun adını verin (n8n, zapier, mobile-app-staging gibi)
Scopes — bu token neler yapabilsin (bir sonraki bölüm)
Expiry — never, 30 days, 90 days, 1 year ya da özel tarih
IP restriction — isteğe bağlı, sadece belirli IP'lerden çağrı kabul etsin

Generate'e basın. Token bir kere tam haliyle görünür. Onu hemen şifre yöneticinize (1Password, AWS Secrets Manager, n8n credentials, ortam değişkeni — "monitörümün kenarındaki post-it" hariç her yere) kopyalayın. Admin arayüzü token'ın sadece bir kısa önekini saklar, tam halini değil — kayboldu mu kurtaramazsınız, yenisini üretip eskisini iptal edersiniz.

Kapsamlar (Scopes)

Kapsamlar, "bu token neleri yapabilsin" kuralıdır. En az yetki ilkesi: gerek olmayan yetki vermeyin. posts:read kapsamlı bir token yazı yazamaz, medya yükleyemez, kullanıcı silemez.

Mevcut kapsamlar:

posts:read — yazıları listele ve oku (taslaklar dahil)
posts:write — yazı oluştur, güncelle, sil
media:read — medya öğelerini listele ve oku
media:write — medya yükle ve sil
categories:read / categories:write
tags:read / tags:write
comments:read / comments:moderate
users:read / users:write — admin yetkisi gerektirir
queue:read / queue:write — içerik kuyruğu
settings:read / settings:write — admin yetkisi gerektirir
* — tam erişim (dikkat; bunu root şifresi gibi koruyun)

Tipik bir senaryo: n8n'de görselli AI taslakları üretip yayınlayan bir akışınız var. O token için sadece posts:write, media:write, categories:read, tags:read yeterli. Dört kapsam, fazlalık yetki yok.

Süre dolumu seçenekleri

Never — siz iptal edene kadar çalışır. Düşük riskli sunucudan sunucuya entegrasyonlar için kabul edilebilir
30 / 90 / 365 days — belirtilen süre sonunda çalışmaz. Dış yükleniciler, zaman sınırlı entegrasyonlar, CI pipeline'ları için iyidir
Custom — elle tarih seçersiniz

Süresi dolmuş token'lar "error": "token_expired" hatasıyla 401 döner. Uzatmak yerine yenisini üretin ve döndürün.

Süre dolumu bir hijyen alışkanlığıdır. "Sonsuz" ayarlı olsa bile yılda bir kez yeni token üretip eskisini kapatmak iyi bir pratiktir.

Token iptal etmek

Settings → API Tokens → satırı bulun → Revoke. 60 saniye içinde etkili olur (token'lar kısa süreli bellek önbelleğinde tutulur, bir dakikadan uzun değil).

Şu durumlarda hemen iptal edin:

Erişimi olan bir ekip üyesi veya yüklenici ayrıldığında
Token'ın sızdığından şüphelendiğinizde (Git'e commit edildi, Slack'te paylaşıldı, bir ekran görüntüsünde yakalandı)
Periyodik güvenlik rotasyonu sırasında

İptal geri alınamaz. İptal edilen satır denetim için arayüzde görünür kalır ama token artık kabul edilmez.

Hız sınırları

Her token'ın kendi kovası var — diğer token'lardan ve anonim trafikten ayrı:

Varsayılan — dakikada 60 istek, saatte 1.000 istek
PRO — dakikada 300, saatte 10.000
Özel — token bazında gelişmiş ayarlardan belirlenir

Kovayı aşarsanız Retry-After başlığı (kova yenilenene kadar geçen saniye) ile 429 Too Many Requests alırsınız:

HTTP/1.1 429 Too Many Requests
Retry-After: 37
Content-Type: application/json

{ "error": "rate_limited", "retry_after": 37 }

İyi yazılmış istemciler Retry-After'ı dinler. n8n'in HTTP Request node'unda Retry on fail seçeneğini açarsanız bunu otomatik yapar.

/api/v1/health uç noktası hız sınırına tabi değil; izleme ajanları kota yemeden ping atabilsin diye.

IP kısıtlaması

Yetki seviyesi yüksek token'lar (* ya da settings:write olanlar) için kaynağı belirli IP'lerle sınırlayın. Token oluştururken IP restriction altına virgülle ayrılmış IPv4/IPv6 adresleri veya CIDR aralıkları yazın.

İzin listesinde olmayan bir IP'den istek gelirse 403 Forbidden döner:

{ "error": "ip_restricted", "message": "source IP not in allowlist" }

IP kısıtlamasıyla süre dolumunu birleştirince — örneğin n8n VPS'inizin IP'sine sınırlı 90 günlük bir token — kontrolsüz "sonsuz" bir token'a göre çok daha güvenli bir kurulum olur.

Özet iyi alışkanlıklar

Her token için en az gereken kapsamı verin
Token adını ait olduğu entegrasyonla eşleştirin
Süre dolumu ayarlayın ve düzenli rotasyona girin
Yüksek yetkili token'ları IP kısıtlamasıyla koruyun
Gizli anahtarları gerçek bir şifre yöneticisinde tutun, Git'te değil
Biri ayrıldığında ya da bir sızıntı şüphesi olduğunda anında iptal edin