API Erişimi: Hesap Anahtarları ve İzinler
Hazırlayan Ersin DorlakSon güncelleme:
Bu Sayfa Ne Yapar
API Erişimi ekranı, hesabınızdaki tüm projelere, yazılara, içerik raporlarına ve bakiyeye kendi yazılımınızdan erişebilmeniz için seçtiğiniz izinlerle sınırlı, spt_ ile başlayan hesap anahtarları üretir, listeler ve iptal eder. Bir ajans paneli, bir otomasyon aracı ya da kendi yazdığınız bir betik panelin yaptığı işleri (yazı üretme, yayınlama, rapor çekme, bot teslimlerini takibe yazma) kullanıcı adınız ve şifreniz olmadan yapabilmelidir; hesap anahtarı bu erişimi verir ve istediğiniz anda geri alınır.
Ekran iki sütundan oluşur. Solda Yeni API anahtarı formu bulunur: Anahtar adı, İzinler listesi, Geçerlilik süresi (gün) ve şifreyle giriş yapan hesaplarda Mevcut şifreniz alanı. Sağda yeni oluşturulan anahtarın bir kez gösterildiği Anahtarınız hazır kartı, Anahtarlarınız listesi ve Geliştirici belgeleri bağlantısı yer alır. Listedeki her satırda anahtar adı, son dört karakteri, izinleri, oluşturulma, son kullanım ve varsa bitiş tarihi görünür.
Anahtar oluşturulduğunda panelde yalnız özeti (karma değeri) saklanır; anahtarın kendisi bir daha gösterilmez. Bir hesapta en fazla 10 anahtar bulunabilir ve saatte en fazla 10 anahtar oluşturulabilir. İstekler /api/public/v1 adresine, anahtar Authorization başlığında Bearer olarak gönderilerek yapılır. Anahtar başına dakikada 120 istek, bunların 30'u yazma isteği olabilir. Her uç nokta tek bir izin ister; anahtarda o izin yoksa istek 403 ile reddedilir. Hesapta aktif plan yoksa istekler 402 döner. Son kullanım zamanı en fazla 5 dakikada bir güncellenir.
Ekranı kullananlar çoğunlukla müşteri sitelerine yazı akışını kendi araçlarından yöneten ajanslar, raporları kendi panosuna çeken danışmanlar ve backlink botunun bıraktığı bağlantıları Bağlantı takibine otomatik yazdırmak isteyen kullanıcılardır. Her entegrasyon için ayrı ve yalnız gereken izinleri taşıyan bir anahtar, bir araç sızdığında yalnız o aracın erişimini kesmenize izin verir.
Bu anahtar, SEO Onarım'ın Kanal & Kurulum sekmesindeki Otopilot API kartında üretilen proje entegrasyon anahtarıyla aynı şey değildir. Proje anahtarı sp_ ile başlar, tek bir projeye bağlıdır ve sitenizin sunucusunun SEO düzeltmelerini çekip uyguladığını bildirmesi içindir. Hesap anahtarı ise tüm projelerinize erişir ve içerik, rapor ve backlink uçlarını kullanır. Ekip üyesi olarak oluşturduğunuz anahtar, projedeki rolünüzün izin verdiğinden fazlasını yapamaz.
Anlatılan sayfayı panelde aç(giriş yapınca açılır)
Ön Koşullar
- Panele giriş yapmış olmanız gerekir; anahtarla yapılan isteklerin çalışması için hesabınızda aktif bir plan bulunmalıdır.
- Şifreyle giriş yapan hesaplarda anahtar oluştururken mevcut şifrenizi girmeniz istenir. Google ile giriş yapıyorsanız son 10 dakika içinde yeniden giriş yapmış olmalısınız.
- Anahtarı kullanacak yazılım sunucu tarafında çalışmalıdır; anahtar tarayıcı koduna, mobil uygulamaya ya da herkese açık bir depoya konmamalıdır.
- content:write izniyle yazı üretilecekse bakiyenizde ya da aylık yapay zekâ hakkınızda yeterli kredi olmalıdır; yayın için projede yazı yayınlayabilen bir kanal bağlı olmalıdır.
Adım Adım Kullanım
- Sol menüde Kullanıcı Ayarları → Abonelik grubundaki API Erişimi öğesine basın. Backlink teslimlerini ayarlıyorsanız Bağlantı takibi ekranındaki API anahtarı oluştur bağlantısı da aynı ekranı açar.
- Anahtar adı alanına anahtarı kullanacak yazılımı tanıtan bir ad yazın (ör. "Ajans paneli" ya da "Backlink botu"); en fazla 60 karakter. Ad listede görünür ve ileride hangi anahtarı iptal edeceğinizi bilmenizi sağlar.
- İzinler listesinde yalnız ihtiyaç duyduğunuz kutuları işaretleyin. Varsayılan olarak hesap, proje ve yazı okuma izinleri seçilidir; bu üçü rapor ve listeleme yapan araçlar için yeterlidir.
- Yazı üretecek ya da düzenleyecek bir araç için content:write iznini ekleyin; bu izin kredi harcayabilir. Yazıyı sitenize gönderecekse content:publish iznini de ekleyin; bu izin yayındaki yazıyı da güncelleyebilir.
- Projenin son 30 günlük içerik sayılarını ve blog planını çekmek için reports:read, backlink botu teslimlerini okumak için backlinks:read, botun bıraktığı bağlantıları takibe yazmak için backlinks:write iznini seçin.
- Geçerlilik süresi (gün) alanına 1 ile 730 arasında bir gün sayısı yazın. Geçici bir iş ya da deneme için kısa süre verin; boş bırakırsanız anahtar siz iptal edene kadar geçerli kalır.
- Şifreyle giriş yapıyorsanız Mevcut şifreniz alanını doldurun ve Anahtar oluştur düğmesine basın. Düğme ad boşsa, hiçbir izin seçilmemişse ya da şifre girilmemişse pasif kalır.
- Sağda açılan Anahtarınız hazır kartındaki anahtarı Kopyala ile alın ve yazılımınızın gizli ayarlarına ya da bir parola yöneticisine kaydedin. Kaydettikten sonra Kaydettim düğmesine basın; kart kapanır ve anahtar bir daha gösterilmez.
- Yazılımınızdan ilk isteği gönderin: GET /api/public/v1/me isteğini Authorization: Bearer başlığıyla yaparak hesap, plan ve bakiye bilgisinin döndüğünü doğrulayın. Uç noktaların tam listesi ve her birinin istediği izin Geliştirici belgeleri bağlantısında yer alır.
- Anahtarlarınız listesinde anahtarın satırını kontrol edin. "Henüz kullanılmadı" ifadesi ilk başarılı istekten sonra "Son kullanım: 17 Kas 10:42" gibi bir tarihe döner; bu, isteğin doğru anahtarla geldiğini gösterir.
- POST isteklerini (yazı üretimi, yayın, bot teslimi) yeniden deneyebilecek bir yapıda gönderiyorsanız her isteğe Idempotency-Key başlığı ekleyin; ağ hatasından sonra aynı anahtarla tekrarlanan istek ikinci kez işlem yapmaz.
- Kullanılmayan, sızdığından şüphelendiğiniz ya da işi biten bir anahtarı silmek için satırdaki çöp kutusu simgesine (İptal et) basın ve onay penceresini kabul edin. Anahtarı kullanan yazılımlar erişimini hemen kaybeder; işlem Hesap Aktivitesi kaydına yazılır.
Ekrandaki öğeler
- Yeni API anahtarı kartı — yeni anahtar oluşturma formu.
- Anahtar adı — en fazla 60 karakterlik ad; altındaki ipucu adın hangi yazılımı tanıttığını hatırlatmak için olduğunu söyler.
- İzinler — sekiz izin kutusu ve açıklamaları: account:read (Hesap ve bakiye bilgisini okur), projects:read (Projeleri listeler), content:read (Yazıları okur), content:write (Yazı üretir ve düzenler, kredi harcayabilir), content:publish (Yazıyı sitenize yayınlar ve yayındaki yazıyı günceller), reports:read (İçerik raporunu okur), backlinks:read (Bağlantı takibi ve bot teslimlerini okur), backlinks:write (Bot teslimlerini bağlantı takibine yazar).
- Geçerlilik süresi (gün) — 1–730 gün; boşsa anahtar iptal edilene kadar geçerlidir.
- Mevcut şifreniz — yalnız şifreyle giriş yapan hesaplarda görünür.
- Anahtar oluştur — ad, en az bir izin ve gerekiyorsa şifre girilince etkinleşir.
- Anahtarınız hazır kartı — anahtarın tamamı, bir daha gösterilmeyeceğini söyleyen uyarı, Kopyala ve Kaydettim düğmeleri.
- Anahtarlarınız listesi — her satırda ad, spt_… ile son dört karakter, izinler, "Oluşturuldu: …", "Son kullanım: …" ya da "Henüz kullanılmadı" ve varsa "Bitiş: …".
- Çöp kutusu düğmesi (İptal et) — onay penceresinden sonra anahtarı siler; "Anahtar iptal edildi." bildirimi çıkar.
- Geliştirici belgeleri bağlantısı — "Uç noktaların listesi:" satırında; hesap anahtarıyla kullanılabilen uçları ve istedikleri izinleri gösterir.
Hesap anahtarıyla kullanılan uç noktalar
- GET /me (account:read) — hesap, plan ve kredi bakiyesi.
- GET /projects (projects:read) — erişebildiğiniz projeler.
- GET /projects/{projectId}/articles ve GET /articles/{articleId} (content:read) — yazıları listeler ve tek yazıyı SEO alanları ve denetim sonuçlarıyla getirir.
- POST /projects/{projectId}/articles ve PATCH /articles/{articleId} (content:write) — yazı üretimini başlatır (bakiyeden düşer) ve yazıyı düzenler.
- POST /articles/{articleId}/publish ve POST /articles/{articleId}/sync (content:publish) — yazıyı bağlı kanala gönderir, yayındaki düzenlemeyi siteye taşır.
- GET /projects/{projectId}/report (reports:read) — son 30 günün içerik sayıları, harcanan kredi ve bu ayın blog planı.
- GET ve POST /projects/{projectId}/backlinks/deliveries (backlinks:read / backlinks:write) — bot teslimlerini listeler ve yeni teslimleri takibe yazar.
Sonuçları nasıl yorumlarsınız
- "Henüz kullanılmadı" yazan bir anahtar, oluşturulduğundan beri hiç başarılı istek almamıştır. Entegrasyonu kurduğunuzu düşünüyorsanız yazılımın başka bir anahtar kullandığını ya da istek adresinin yanlış olduğunu gösterir.
- "Son kullanım" tarihi beklemediğiniz kadar yeniyse ve o saatte bir iş çalıştırmadıysanız anahtar başka bir yerde kullanılıyor olabilir; anahtarı iptal edip yenisini oluşturun.
- Hata yanıtlarındaki durum kodları: 401 anahtar geçersiz ya da gönderilmemiş, 403 izin yok, 402 kredi yetersiz ya da plan gerekli, 422 yazının bloklayan bir denetim kontrolü var, 429 dakikalık sınır aşıldı.
- Bitiş tarihi yaklaşan anahtarlar kendiliğinden yenilenmez; tarih geçince istekler 401 döner. Süreli anahtar kullanıyorsanız bitişten önce yenisini oluşturup yazılımınızda değiştirin.
Örnek senaryo
Bir ajans, örnek.com dahil müşteri sitelerinin yazı akışını kendi proje yönetim aracından yürütmek istiyor. Ajans geliştiricisi API Erişimi ekranında "Ajans paneli" adıyla bir anahtar oluşturuyor; varsayılan okuma izinlerine content:write ve content:publish izinlerini ekliyor, süreyi boş bırakıyor ve şifresini girip Anahtar oluştur düğmesine basıyor. Anahtarınız hazır kartındaki anahtarı kopyalayıp aracın gizli ayarlarına kaydediyor, ardından Kaydettim ile kartı kapatıyor.
Araç önce GET /api/public/v1/projects ile proje listesini alıyor, örnek.com projesinin kimliğini buluyor ve POST isteğiyle yeni bir yazı üretimini Idempotency-Key başlığıyla başlatıyor; yanıt 202 ve yazı kimliğiyle dönüyor. Yazı hazır olunca araç publish ucunu çağırıyor ve yazı projeye bağlı kanal üzerinden siteye taslak olarak gidiyor. Anahtarlarınız listesinde satır "Son kullanım: …" tarihine dönüyor.
Aynı ajans backlink botu için ayrı bir anahtar oluşturuyor ve yalnız backlinks:write iznini veriyor; 90 günlük süre tanımlıyor. Bot sunucusu bir gün başka bir ekibe devredildiğinde ajans yalnız bu anahtarı İptal et ile siliyor; yazı akışı ilk anahtarla çalışmaya devam ediyor.
İpuçları
- Her yazılım için ayrı anahtar oluşturun ve adını yazılımın adı yapın; iptal gerektiğinde tek bir entegrasyonu durdurursunuz.
- Yalnız okuyan araçlara (raporlama, pano) content:write ve content:publish vermeyin; bu iki izin kredi harcayabilir ve sitenize yazabilir.
- Anahtarı bir ortam değişkeninde ya da gizli anahtar yöneticisinde tutun; kod deposuna eklemeyin.
- Yayın uçları paneldeki denetimlerden geçer: bloklayan kontrolü olan yazı yayınlanmaz. 422 alırsanız yazıyı panelde açıp denetim sonucunu düzeltin.
- Sitenizin kodu SEO düzeltmelerini çekecekse hesap anahtarı yerine SEO Onarım'daki proje anahtarını kullanın; düzeltme uçları hesap anahtarını kabul etmez.
- Anahtar izinleri sonradan değişmez; izin eklemek için yeni anahtar oluşturup eskisini iptal etmek gerekir. İzinleri baştan iş akışına göre planlayın.
Sık yapılan hatalar
- Kaydettim düğmesine anahtarı kopyalamadan basmak; anahtar bir daha gösterilmez ve yenisini oluşturmak gerekir.
- Proje entegrasyon anahtarını (sp_) hesap API'sine göndermek ya da hesap anahtarını (spt_) SEO düzeltme uçlarında denemek; iki anahtar farklı uçlar içindir.
- Tüm izinleri tek anahtarda toplayıp bu anahtarı birden çok araca dağıtmak; bir araç sızdığında hepsinin erişimini kesmek gerekir.
- Kullanılmayan anahtarları listede bırakmak; 10 anahtar sınırı dolduğunda yeni entegrasyon kurulamaz.
Sık Karşılaşılan Sorunlar
- Mevcut şifre hatalı.: Anahtar oluştururken girdiğiniz şifre hesabınızın şifresiyle eşleşmedi. Şifrenizi yeniden yazın; hatırlamıyorsanız çıkış yapıp giriş ekranındaki şifre sıfırlama adımını kullanın.
- Google ile giriş yaptığınız için güvenlik amacıyla son 10 dakika içinde yeniden giriş yapmanız gerekir.: Şifresiz (Google) hesaplarda anahtar oluşturmak taze bir oturum ister. Çıkış yapıp Google ile yeniden giriş yapın ve 10 dakika içinde anahtarı oluşturun.
- En fazla 10 anahtar oluşturabilirsiniz.: Hesabınızdaki anahtar sayısı sınıra ulaştı. Anahtarlarınız listesinde "Henüz kullanılmadı" yazan ya da artık kullanmadığınız anahtarları İptal et ile silin, ardından yenisini oluşturun.
- Bu işlem için API anahtarında "content:publish" izni açık değil.: İstek, anahtarda bulunmayan bir izin gerektiren uca gönderildi. Anahtarın izinleri sonradan değiştirilemez; gereken izinlerle yeni bir anahtar oluşturun, yazılımınızda eskisinin yerine koyun ve eski anahtarı iptal edin.
- API anahtarı geçersiz.: Anahtar yanlış kopyalanmış, iptal edilmiş ya da geçerlilik süresi dolmuş olabilir; proje entegrasyon anahtarı (sp_) gönderilmiş olması da aynı hataya yol açar. Listede anahtarın son dört karakterini ve bitiş tarihini kontrol edin, gerekirse yeni anahtar oluşturun.
- Bu özelliği kullanmak için aktif bir plan gerekir.: Anahtar geçerli ama hesabınızda aktif plan olmadığı için istek 402 ile reddedildi. Paketleri Gör ekranından plan seçin ya da aboneliğinizi yenileyin; anahtarı yeniden oluşturmanız gerekmez.
- Çok fazla istek. Biraz sonra tekrar dene.: Anahtar başına dakikalık 120 istek ya da 30 yazma isteği sınırı aşıldı. Yanıttaki Retry-After başlığında belirtilen süre (60 saniye) kadar bekleyin ve istekleri zamana yayın.
- Henüz API anahtarınız yok.: Hesabınızda hiç hesap anahtarı oluşturulmamış ya da tümü iptal edilmiş. Soldaki formu doldurup Anahtar oluştur ile ilk anahtarınızı oluşturun.
İlgili Kılavuzlar
Bu adımları kendi sitenizde uygulayın
Önce ücretsiz site analiziyle sitenizdeki sorunları görün. Hesabınız varsa rehberde anlatılan sayfayı panelde açın.