Kanzen Ads Docs
IntroductionQuickstartAuthentication
Connect to Hermes Agent
Payments / Top-up
Overview & CreditsGenerate ImageGenerate VideoRetrieve Media
Top Up Campaign AdsCharacter + Product Video
Errors & LimitsAPI ReferenceMeta Marketing API Guide

Autentikasi

Satu key nutup semua kebutuhan agent Hermes: user key hsk_ autentikasi Generation + Knowledge API (/api/gen/*).

❗

Key yang mana?

Key hsk_ aja yang agent butuhin — tools generation dan knowledge semuanya terima key yang sama. Key agent legacy masih diterima di endpoint-endpoint ini demi backward compatibility, tapi integrasi baru harus cuma provision dan pakai satu key hsk_ aja.

Ambil dari mana

Generate key-nya dari Hermes Settings (/hermes-settings) → "Generate Token Hermes". Nilai mentahnya cuma ditampilin sekali pas dibikin — langsung disalin ya; yang kesimpen di server cuma hash-nya.

Generation + Knowledge API (/api/gen/*)

Sesuai yang keverifikasi di kode (src/lib/api-key-auth.ts): dua-duanya header jalan — server cek x-api-key dulu, terus fallback ke Authorization: Bearer kalau nggak ada.

Opsi A — x-api-key (disarankan)
curl -H "x-api-key: hsk_your_key" \
  https://kanzenads.com/api/gen/credits
Opsi B — Authorization: Bearer
curl -H "Authorization: Bearer hsk_your_key" \
  https://kanzenads.com/api/gen/credits

Legacy: Content API (/api/hermes/*)

Endpoint content-agent yang lama (library, ready-upload, content-log, photos, cep-feedback) masih jalan di model kunci-agent lama + assignment, terpisah dari alur satu-kunci di atas. Perkecualian: CEP — GET/POST /api/hermes/ceps dan DELETE /api/hermes/ceps/:id sudah migrasi (2026-07-24) ke kunci hsk_ yang sama (lewat authenticateApiCaller), di-scope lewat kepemilikan produk/topik, bukan assignment lagi; kunci agent lama tetap diterima di dua route itu sebagai fallback. cep-feedback (jalur usulan CEP dari agent) TIDAK ikut migrasi ini — tetap butuh kunci agent Bearer lama. Lihat bagian CEP di halaman Connect to Hermes Agent untuk detail.

Siklus hidup key

  • Key di-hash saat disimpan (SHA-256) — nilai mentahnya cuma ditampilin sekali pas dibikin dan nggak bisa diambil lagi selamanya.
  • Key harus punya status: 'active' buat bisa autentikasi; revoke bikin langsung inactive.
  • Tiap request yang sukses update lastUsedAt secara asinkron (nggak nge-block request).

Ringkasan

SistemPrefixHeader yang diterimaCakupan
User key (Hermes Settings)hsk_x-api-key atau Authorization: Bearer/api/gen/*
Key agent legacy(pre-hsk_)Authorization: Bearer/api/hermes/*
← QuickstartConnect to Hermes Agent →