Ajanlar için API anahtarları: okuma, yazma, yayınlama ve gerçekten bakacağınız bir denetim kaydı

Her ajana, işini görecek en dar Shager anahtarını verin: raporlama için read, taslak hazırlamak için write ve publish yalnızca gönderileri planlayan adım için. Anahtarları istemlerde değil, ortam değişkenlerinde ya da MCP istemcisinin yapılandırmasında tutun. İptal ve yenileme işlemlerini ajan panelinden yapın; yeni bir ajan yerine oturana kadar da bir ajanın yaptığı her çağrıyı listeleyen denetim kaydını en az haftada bir okuyun.

Politika bu kadar. Yazının geri kalanı gerekçeyi ve işleyişi anlatıyor, çünkü kimsenin anlamadığı bir politika ilk zahmetli anda devre dışı bırakılır.

Her yetki neler yapabilir?

Her Shager anahtarı üç yetkiden (scope) birini ya da birkaçını taşır. API'deki her işlem ihtiyaç duyduğu yetkiyi belirtir; bunu OpenAPI belgesinde her işlemin x-scope alanında görebilirsiniz. MCP araçları aynı işlemlerdir, dolayısıyla MCP üzerinden de aynı kurallar geçerlidir.

Yetki	İşlemler
read	whoami, list_workspaces, list_channels, list_groups, list_posts, get_post, get_analytics
write	create_workspace, create_connect_link, create_group, upload_media_from_url, create_post, request_approval, cancel_post
publish	schedule_post

Bu tabloda iki şey dikkati hak ediyor.

Birincisi, publish tek bir işlem içerir ve bu, içeriği müşteri hesaplarında yayına sokan işlemdir. Onu ayrı tutmanın amacı da budur. Bir ajan, medya yüklemekten hesaba özel açıklama taslakları yazmaya ve onay linkleri göndermeye kadar işin neredeyse tamamını, bir Sayfaya tek bir gönderi koyabilme imkânı olmadan yapabilir.

İkincisi, cancel_post işlemi write altında yer alır. Taslak hazırlayan bir ajan, planlanmış bir gönderiyi taslağa geri çekebilir. Bu bilinçli bir tercih: bir hatayı durdurmak, hata yapmaktan daha kolay olmalı.

Gerekli yetki olmadan kullanılan bir anahtar, HTTP 403 ile standart yapıda bir hata alır: { "error": { "code", "message" } }. Ajanlar başka bir yol aramak yerine bu hatayı raporlamalıdır; kalıcı talimatlarınız da bunu söylemelidir.

Diyagramın tamamı için yana kaydırın

Anahtarlar nereden gelir?

İki yol var.

Anahtarı bir insan oluşturur: app.shager.ai/dashboard/agents adresinde yetkileri seçerek. Mevcut bir hesaba ajan ekleyen bir ajans için olağan yol budur.

Ajan kendi kendine kaydolur. Hesabı olmayan bir ajan, bir agent_name ve tercihen insanı için bir contact_email ile POST https://app.shager.ai/api/v1/agent/signup çağrısını yapar. Yalnızca bir kez gösterilen bir api_key ve bir claim_url alır. Bu anahtar hemen bir test ortamında çalışır; test ortamı en fazla beş çalışma alanı oluşturabilir, medya yükleyebilir, taslak oluşturabilir ve okuma yapabilir. Planlama ya da yayın yapamaz, müşteri bağlantı linki oluşturamaz, onay isteği gönderemez.

curl -s https://app.shager.ai/api/v1/agent/signup \
  -H "Content-Type: application/json" \
  -d '{"agent_name":"Northwind content agent (Claude Code)",
       "contact_email":"ops@northwind-agency.example",
       "purpose":"Draft weekly posts for 3 retail clients"}'

Bu kısıtlamalar ancak bir insan claim_url linkini açıp giriş yaptığında ve kuruluşu sahiplendiğinde kalkar. O anda insan, ajanın anahtarının publish yetkisini de alıp almayacağına karar verir. Kimse sahiplenmezse test ortamının süresi yedi gün sonra dolar. Tarifin tamamı /auth.md adresinde yayımlanmıştır; adım adım anlatım ise ajanın kendi kendine kaydı ve sahiplenme yazısında.

Bunun arkasındaki tasarım tercihi basit: Bir ajan kendi başına keşfedip hazırlık yapabilir, ama gerçek hesapları bağlamak ve onlarda yayın yapmak her zaman bir insandan geçer.

Ajanlar anahtarları nasıl saklamalı ve göndermeli?

Shager anahtarları Authorization: Bearer shgr_live_... olarak gönderilen bearer token'lardır. RFC 6750'nin ifadesiyle bir bearer token'ın belirleyici özelliği, ona sahip olan herkesin onu kullanabilmesidir. Kimliği kanıtlayan başka bir şey yoktur. Yani bütün iş, onu sızdırmamaktır.

Pratikte:

1. Yapılandırmanın başvurduğu ortam değişkenleri. Claude Code, MCP belgelerine göre .mcp.json başlıklarında ${VAR} genişletmesini destekler. Dosya depoya eklenebilir; anahtar ortamda kalır.
2. Asla bir istemde değil. Sohbete yapıştırılan bir anahtar dökümlere ve loglara, bazen de paylaşılan konuşmalara düşer.
3. Asla bir müşteri klasöründe değil. Müşteri bazında bağlam klasörleri tutuyorsanız, anahtarların oralarda yeri yoktur. O klasörler paylaşılır ve sıkıştırılıp gönderilir.
4. Her ajan rolüne bir anahtar. Bir raporlama işi, bir taslak ajanı ve bir planlama adımı aynı anahtarı paylaşmamalı. Biri sızdığında yalnızca birini iptal edersiniz.

{
  "mcpServers": {
    "shager": {
      "type": "http",
      "url": "https://app.shager.ai/api/mcp",
      "headers": { "Authorization": "Bearer ${SHAGER_DRAFT_KEY}" }
    }
  }
}

Shager'ın MCP sunucusu bu API anahtarı başlığını kabul eder. Bunun yerine OAuth ile giriş yaparak bağlanan istemciler de, örneğin Claude veya ChatGPT'deki özel bir bağlayıcı, aynı denetimi alır: Bağlantıyı bir insan Shager'ın onay ekranında onaylar, yayınlama varsayılan olarak kapalı olan ayrı bir onay kutusudur ve bağlantı aynı denetim kaydında görünür. ChatGPT kurulumunu Shager ve ChatGPT yazısında adım adım anlatıyoruz.

Kesintisiz anahtar yenileme

Erişimi olan biri ayrıldığında, bir anahtarın açığa çıkmış olabileceği durumlarda ve uyabileceğiniz bir takvime göre anahtarlar yenilenmelidir. Boşluk bırakmayan sıra:

1. Panelde aynı yetkilere sahip yeni bir anahtar oluşturun.
2. Ajanın çalıştığı yerdeki ortam değişkenini güncelleyin.
3. Çalıştığını ve beklenen yetkileri gösterdiğini doğrulamak için yeni anahtarla whoami çalıştırın.
4. Eski anahtarı iptal edin.

İptal, MCP ve REST fark etmeksizin o anahtarla yapılan her çağrı için geçerli olur.

Diyagramın tamamı için yana kaydırın

İstek sınırları da güvenliğin parçası

Her anahtar dakikada 120 istekle sınırlıdır. Düzgün çalışan bir ajan bu sınıra hiç yaklaşmaz: bir müşteri için haftalık taslakların tamamı birkaç düzine çağrıdır. Bir ajan HTTP 429 alıyorsa bu genellikle bir döngü anlamına gelir; ajan aynı başarısız çağrıyı tekrar tekrar deniyordur. Talimatlarınız 429'u daha hızlı yeniden denemek için bir neden değil, bir dur işareti olarak ele almalı. Geri çekilin, raporlayın ve bir insanın bakmasına izin verin.

Denetim kaydını okumak

Ajan paneli, her ajan çağrısının denetim kaydını gösterir. Bu kayıt ancak biri okursa işe yarar. Yeni bir ajanla geçen ilk haftalarda nelere bakmalı:

1. Beklemediğiniz çağrılar. create_post çağıran bir raporlama ajanı, talimatlarının ya da anahtarının yanlış olduğu anlamına gelir.
2. Çalışma alanı kayması. Görevle ilgisi olmayan bir müşteriye dokunan çağrılar. Bu, tek ajan, birçok müşteri yazısında ele aldığımız müşteriler arası hatanın erken uyarısıdır.
3. Hata patlamaları. Tekrarlayan 403'ler, ajanın yetkisi dışındaki bir şeyi denemeye devam ettiğini gösterir. Yetkiyi değil, talimatları düzeltin.

Birkaç sorunsuz haftadan sonra haftalık hızlı bir göz atma yeterlidir.

SSS

Ajan hiç publish yetkisine sahip olmalı mı?

Taslaklarına güvendiğinizde ve bir inceleme adımınız olduğunda olabilir; müşteri onay linkleri ya da şirket içi bir onaylayan. İyi işleyen bir kalıp, publish yetkisini yalnızca kısa, betikle yazılmış bir planlama adımının kullandığı ayrı bir anahtarda tutmaktır; böylece yazan ajan, yayına gönderen ajan olmaz.

Test ortamı sahiplenildiğinde ajanın anahtarına ne olur?

Kuruluş insana geçer ve anahtar onun içinde çalışmaya devam eder. İnsan, sahiplenme sırasında bu anahtarın planlama ve yayın da yapıp yapamayacağını seçer. İstediği zaman panelden anahtarı iptal edebilir ya da yenilerini oluşturabilir.

Bir anahtar tek bir müşteri çalışma alanıyla sınırlandırılabilir mi?

Yetkiler, bir anahtarın hangi çalışma alanında işlem yaptığını değil, ne yapabildiğini sınırlar. Müşterileri çalışma alanları, müşteri bazında bağlam ve her yazma işleminden önce çalışma alanını adıyla çözümleme alışkanlığıyla ayırın; iptalin nokta atışı olması için de her role ayrı anahtar kullanın.

Buradan nereye?

İlk ajanınızı kuruyorsanız, ajan giriş noktası bir anahtara giden iki yolu da gösterir. write anahtarıyla başlayın ve publish yetkisini ancak taslaklar bunu hak ettiğinde ekleyin.