Kunci API untuk Agen: Read, Write, Publish, dan Log Audit yang Benar-Benar Anda Periksa

Beri setiap agen kunci Shager dengan cakupan sesempit mungkin yang masih cukup untuk tugasnya: read untuk pelaporan, write untuk menyusun draf, dan publish hanya untuk langkah yang menjadwalkan postingan. Simpan kunci di variabel lingkungan atau konfigurasi klien MCP, jangan pernah di dalam prompt. Cabut dan rotasi kunci dari dashboard agen, dan baca log auditnya, yang mencatat setiap panggilan yang dilakukan agen, minimal seminggu sekali selama agen baru masih dalam masa adaptasi.

Itulah kebijakannya. Sisa artikel ini menjelaskan alasan dan mekanismenya, karena kebijakan yang tidak dipahami siapa pun akan diakali begitu terasa merepotkan.

Apa yang bisa dilakukan tiap scope?

Setiap kunci Shager membawa satu atau lebih dari tiga scope. Setiap operasi di API menyatakan scope yang dibutuhkannya; Anda bisa melihatnya sebagai x-scope pada setiap operasi di dokumen OpenAPI. Tools MCP adalah operasi yang sama, jadi aturan yang sama juga berlaku lewat MCP.

Scope	Operasi
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

Ada dua hal di tabel itu yang patut diperhatikan.

Pertama, publish hanya berisi satu operasi, dan operasi itulah yang membuat konten tayang di akun klien. Mengisolasinya memang tujuannya. Agen bisa mengerjakan hampir semua pekerjaan, mulai dari mengunggah media, menyusun caption per akun, hingga mengirim tautan persetujuan, tanpa pernah bisa menaruh satu postingan pun di sebuah Halaman.

Kedua, cancel_post berada di bawah write. Agen penyusun draf bisa menarik postingan terjadwal kembali menjadi draf. Ini disengaja: menghentikan kesalahan semestinya lebih mudah daripada membuatnya.

Kunci yang dipakai tanpa scope yang diperlukan akan menerima error dalam format standar, { "error": { "code", "message" } }, dengan HTTP 403. Agen sebaiknya melaporkan error itu alih-alih mencari jalan memutar, dan instruksi tetap Anda harus menyatakannya dengan jelas.

Geser ke samping untuk melihat seluruh diagram

Dari mana kunci berasal

Ada dua jalur.

Manusia membuat kuncinya di app.shager.ai/dashboard/agents, sambil memilih scope-nya. Ini jalur normal bagi agensi yang menambahkan agen ke akun yang sudah ada.

Agen mendaftar sendiri. Agen yang belum punya akun memanggil POST https://app.shager.ai/api/v1/agent/signup dengan agent_name dan, idealnya, contact_email milik manusianya. Agen menerima api_key, yang hanya ditampilkan sekali, serta claim_url. Kunci itu langsung berfungsi di dalam sandbox, yang bisa membuat hingga lima workspace, mengunggah media, membuat draf, dan membaca data. Kunci itu tidak bisa menjadwalkan atau memublikasikan, membuat tautan koneksi klien, atau mengirim permintaan persetujuan.

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"}'

Pembatasan itu baru dicabut ketika seorang manusia membuka claim_url, masuk, dan mengklaim organisasinya. Pada saat itulah manusia memutuskan apakah kunci agen juga mendapat publish. Jika tidak ada yang mengklaim, sandbox kedaluwarsa setelah tujuh hari. Panduan lengkapnya dipublikasikan di /auth.md, dan penjelasan langkah demi langkahnya ada di pendaftaran mandiri dan klaim oleh agen.

Prinsip desain di baliknya sederhana: agen boleh menjelajah dan bersiap sendiri, tetapi menghubungkan akun sungguhan dan memublikasikan ke akun itu selalu melewati tangan manusia.

Bagaimana agen sebaiknya menyimpan dan mengirim kunci?

Kunci Shager adalah bearer token yang dikirim sebagai Authorization: Bearer shgr_live_.... Sifat utama bearer token, sebagaimana dirumuskan RFC 6750, adalah bahwa siapa pun yang memegangnya bisa memakainya. Tidak ada hal lain yang membuktikan identitas. Jadi seluruh tugasnya adalah memastikan kunci tidak bocor.

Dalam praktiknya:

1. Variabel lingkungan, dirujuk dari konfigurasi. Claude Code mendukung ekspansi ${VAR} di header .mcp.json, sesuai dokumentasi MCP-nya. File itu boleh di-commit; kuncinya tetap di environment.
2. Jangan pernah di dalam prompt. Kunci yang ditempel di chat akan tersimpan di transkrip dan log, kadang juga di percakapan yang dibagikan.
3. Jangan pernah di folder klien. Jika Anda menyimpan folder konteks per klien, kunci tidak boleh ada di sana. Folder seperti itu sering dibagikan dan di-zip.
4. Satu kunci per peran agen. Tugas pelaporan, agen penyusun draf, dan langkah penjadwalan tidak boleh berbagi kunci. Kalau satu bocor, Anda cukup mencabut satu.

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

Server MCP Shager menerima header kunci API ini. Klien yang terhubung lewat login OAuth, seperti konektor kustom di Claude atau ChatGPT, mendapat kendali yang sama: manusia menyetujui koneksinya di layar persetujuan Shager, publikasi adalah kotak centang terpisah yang nonaktif secara default, dan koneksinya muncul di log audit yang sama. Shager dan ChatGPT menjelaskan langkah penyiapan di ChatGPT.

Rotasi tanpa downtime

Kunci sebaiknya dirotasi ketika ada orang dengan akses yang keluar, ketika sebuah kunci mungkin sudah terekspos, dan secara berkala sesuai jadwal yang sanggup Anda jalankan. Urutan yang mencegah adanya jeda:

1. Buat kunci baru dengan scope yang sama di dashboard.
2. Perbarui variabel lingkungan di tempat agen berjalan.
3. Jalankan whoami dengan kunci baru untuk memastikan kunci berfungsi dan menampilkan scope yang diharapkan.
4. Cabut kunci lama.

Pencabutan berlaku untuk setiap panggilan yang dibuat dengan kunci tersebut, baik lewat MCP maupun REST.

Geser ke samping untuk melihat seluruh diagram

Batas request adalah bagian dari keamanan

Setiap kunci dibatasi 120 request per menit. Agen yang tertib tidak akan pernah mendekati angka itu: satu set draf mingguan lengkap untuk satu klien hanya butuh beberapa puluh panggilan. Jika agen sampai terkena HTTP 429, biasanya itu tanda ada loop, yaitu agen yang mencoba ulang panggilan gagal yang sama berkali-kali. Instruksi Anda sebaiknya memperlakukan 429 sebagai sinyal berhenti, bukan alasan untuk mencoba ulang lebih cepat. Mundur, laporkan, dan biarkan manusia memeriksanya.

Membaca log audit

Dashboard agen menampilkan log audit dari setiap panggilan agen. Log itu hanya berguna jika ada yang membacanya. Yang perlu dicari di minggu-minggu pertama bersama agen baru:

1. Panggilan yang tidak Anda duga. Agen pelaporan yang memanggil create_post berarti instruksi atau kuncinya keliru.
2. Pergeseran workspace. Panggilan yang menyentuh klien di luar cakupan tugasnya. Ini peringatan dini untuk kesalahan lintas klien yang dibahas di satu agen, banyak klien.
3. Lonjakan error. 403 yang berulang berarti agen terus mencoba sesuatu di luar scope-nya. Perbaiki instruksinya, bukan scope-nya.

Setelah beberapa minggu tanpa masalah, cukup sekilas tinjau seminggu sekali.

FAQ

Apakah agen boleh memegang scope publish?

Boleh, setelah Anda memercayai kualitas drafnya dan memiliki tahap peninjauan, entah lewat tautan persetujuan klien atau peninjau internal. Pola yang terbukti baik adalah menyimpan publish di kunci terpisah yang hanya dipakai oleh langkah penjadwalan singkat berbasis skrip, sehingga agen yang menulis bukanlah agen yang memublikasikan.

Apa yang terjadi pada kunci agen saat sandbox diklaim?

Organisasinya menjadi milik manusia tersebut, dan kuncinya tetap berfungsi di dalamnya. Saat klaim, manusia memilih apakah kunci itu juga boleh menjadwalkan dan memublikasikan. Ia bisa mencabutnya atau membuat kunci baru dari dashboard kapan saja.

Bisakah sebuah kunci dibatasi ke satu workspace klien saja?

Scope membatasi apa yang bisa dilakukan kunci, bukan workspace mana yang disentuhnya. Pisahkan klien lewat workspace, konteks per klien, dan kebiasaan mencari workspace berdasarkan namanya sebelum setiap operasi tulis, lalu gunakan kunci terpisah per peran agar pencabutan tetap presisi.

Langkah selanjutnya

Jika Anda sedang menyiapkan agen pertama, titik masuk agen menunjukkan kedua jalur untuk mendapatkan kunci. Mulailah dengan kunci write, dan tambahkan publish hanya setelah draf-drafnya terbukti layak.