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

_2026-10-01 · Memberi agen AI kunci API Shager dengan aman: fungsi read, write, dan publish, klaim sandbox, penyimpanan kunci, batas request, rotasi kunci, dan log audit._

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](https://app.shager.ai/api/v1/openapi.json). 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.

## 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.

```bash
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](/auth.md), dan penjelasan langkah demi langkahnya ada di [pendaftaran mandiri dan klaim oleh agen](/en/blog/agent-self-signup-and-claim).

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](https://www.rfc-editor.org/rfc/rfc6750), 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](https://code.claude.com/docs/en/mcp). 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.

```json
{
  "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](/en/blog/shager-and-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.

## 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](/en/blog/one-agent-many-clients).
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](/en/agents) menunjukkan kedua jalur untuk mendapatkan kunci. Mulailah dengan kunci `write`, dan tambahkan `publish` hanya setelah draf-drafnya terbukti layak.

---
Source: https://shager.ai/id/blog/api-keys-scopes-and-audit