API key

API key bikin kodemu sendiri bisa ngobrol sama Publiz: menjadwalkan post dari CMS-mu, menarik aset ke proses build, atau menjalankan job AI lewat script. Satu key melekat ke satu workspace dan cuma membawa scope yang kamu kasih.

Tempatnya di Developer lalu API Keys di sidebar.

Bikin satu

1. Klik Create API Key.

2. Kasih nama yang nanti kamu kenali. Cuma itu cara membedakan key setelah dibuat, jadi “Zapier automation” jauh lebih berguna daripada “key 2”.

3. Centang resource yang dibutuhin. Yang nggak bisa dikasih paketmu tampil abu-abu dengan label Not on your plan.

   

4. Kalau mau, set tanggal kedaluwarsa. Dikosongin berarti key-nya jalan sampai kamu cabut. Mengisinya layak buat sesuatu yang berumur pendek, misalnya script migrasi.

5. Klik Create. Key-nya muncul sekali.

Salin key-nya saat itu juga

Key lengkapnya ditampilkan sekali, tepat setelah dibuat. Publiz cuma menyimpan hash-nya, jadi nggak ada yang bisa menunjukkannya lagi, termasuk kami. Kalau hilang, satu-satunya jalan adalah me-reset key itu, yang menerbitkan key baru dan bikin apa pun yang memakai key lama berhenti jalan.

Setelah itu, daftarnya cuma menampilkan beberapa karakter awal sebagai prefix, misalnya pk_7f3a91…, yang sudah cukup buat tahu sebuah baris log punya key yang mana.

Scope

Sebuah key cuma menjangkau yang kamu centang. Kasih tiap integrasi sesedikit mungkin — key yang cuma menerbitkan post nggak bisa sekalian menghapus mediamu.

Scope	Cakupannya
Posts	Baca, bikin, ubah, hapus, terbitkan, dan coba ulang post
Ideas	Baca dan kelola ide konten, termasuk men-generate
Media	Daftar, unduh, unggah, dan hapus aset
AI	Menjalankan tool AI
Accounts	Menampilkan akun sosial yang terhubung. Cuma baca, nggak bisa menghubungkan akun lewat API
Members	Belum ada, lihat di bawah
Webhooks	Belum ada, lihat di bawah
Comments	Belum ada, lihat di bawah

Tiga scope belum punya endpoint

Members, Webhooks, dan Comments bisa dicentang kalau paketmu mengizinkan, tapi belum ada endpoint yang menerimanya, jadi key yang memegangnya tetap nggak bisa ngapa-ngapain soal member, webhook, atau komentar. Kelola lewat dashboard dulu — member dan komentar punya halamannya masing-masing. Mencentangnya nggak merugikan, dan key yang sudah memegangnya bakal langsung jalan begitu endpoint-nya ada.

Scope mana yang bisa kamu kasih tergantung paketmu:

Paket	Jumlah key	Scope yang tersedia
Free	nggak ada	—
Creator	1	Posts, Ideas, Media, Webhooks
Pro	3	semua di atas, plus Accounts dan Members
Agency	5	semuanya, termasuk Comments dan AI

Halamannya menampilkan posisimu, misalnya “2 of 3 keys used”. Kalau sudah mentok, tombol Create API Key mati sampai kamu mencabut salah satu.

Member butuh izin

Member workspace cuma melihat halaman ini kalau sudah dikasih izin API keys. Owner selalu punya. Lihat workspace dan member.

Memakai key-nya

Kirim lewat header X-API-Key. API-nya ada di https://api.publiz.xyz/v1.

curl https://api.publiz.xyz/v1/me \
  -H "X-API-Key: pk_key_kamu_di_sini"

/me panggilan pertama yang berguna: dia ngasih tahu key-nya milik workspace mana dan memegang scope apa saja, tanpa butuh scope apa pun.

Bikin post kira-kira begini:

curl -X POST https://api.publiz.xyz/v1/posts \
  -H "X-API-Key: pk_key_kamu_di_sini" \
  -H "Content-Type: application/json" \
  -d '{"content": "Batch baru barusan mendarat.", "platforms": ["bluesky"]}'

Daftar endpoint lengkapnya, beserta scope yang dibutuhkan masing-masing, ada di referensi API. Ada juga SDK resmi TypeScript, Go, dan Dart kalau kamu males nulis HTTP-nya sendiri.

Satu hal yang nggak bisa dilakukan sebuah key: mengelola API key. Membuat, me-reset, dan mencabut key semuanya butuh user yang login, jadi sebuah key nggak akan pernah bisa menerbitkan key lain.

Generate AI itu asinkron

Endpoint AI menjawab 202 beserta jobId, bukan hasil jadinya. Poll GET /v1/ai/jobs/{jobId} sampai status jadi COMPLETED atau FAILED. Kamu juga bisa menghitung harga sebuah job sebelum menjalankannya dengan mengirim body yang sama ke path /estimate milik tool itu, dan itu nggak memotong kredit.

Batas permintaan

Batasnya per key, per menit, dan beda-beda tergantung jenis panggilannya:

Jenis permintaan	Per menit
Baca, termasuk polling status job	600
Tulis ke post dan ide	60
Unggah	30
Generate AI	10

Generate paling ketat karena tiap job memotong kredit dan memanggil provider. Kalau kamu memproses banyak sekaligus, kasih jeda kecil antar job daripada menembakkan semuanya berbarengan.

Rotasi dan pencabutan

Tiap baris punya tiga aksi:

• Edit (pensil) mengubah scope yang dipegang sebuah key, tanpa mengubah key-nya. Nggak ada yang perlu di-deploy ulang.
• Reset (panah) menerbitkan key baru buat baris yang sama, nama dan scope-nya tetap. Key lama langsung berhenti jalan, dan yang baru ditampilkan sekali, sama kayak waktu dibuat. Ini yang dipakai kalau sebuah key bocor.
• Revoke (tong sampah) menghapus key-nya permanen. Nggak bisa dibatalkan.

Kolom Last Used di tiap baris ngasih tahu apakah sebuah key masih kepakai, dan itu cara termudah menemukan yang aman dicabut.

Key yang bocor itu key yang hidup

Sebuah key jalan dari mana pun sampai di-reset atau dicabut, dan dia bisa melakukan semua yang diizinkan scope-nya. Jauhkan key dari kode sisi klien dan dari git, dan reset begitu kamu curiga dia kebuka.

Kalau nggak jalan

missing X-API-Key header — header-nya nggak terkirim. Cek ejaannya dan pastikan klienmu nggak membuang header custom waktu kena redirect.

unauthorized: invalid api key — key-nya salah, atau sudah di-reset atau dicabut. Bandingkan prefix di error dengan prefix yang ada di halaman ini.

unauthorized: api key expired — key-nya punya tanggal kedaluwarsa dan tanggalnya sudah lewat. Reset key-nya atau bikin yang baru.

403 yang menyebut resource tertentu — key-nya valid tapi nggak memegang scope itu. Edit dan centang resource-nya, selama paketmu mengizinkan.

“the … scope is not enabled on your plan” — masalah yang beda, dan kalimatnya sengaja dibedakan. Key-nya memang memegang scope itu, tapi paketmu sudah nggak mencakupnya lagi. Ini yang muncul setelah turun paket: scope-nya tetap kelihatan di halaman, ditandai Kept from a previous plan, dan berhenti jalan sampai kamu naik paket lagi.

404 di sesuatu yang kamu kira ada — cek referensi API. Member, webhook, dan komentar punya scope tapi belum punya endpoint, jadi memang nggak ada yang bisa dipanggil di path itu.

Semuanya balik 401 di paket gratis. Paket gratis nggak dapat API key sama sekali, jadi memang nggak ada key yang bisa dibuat.