JAKARTA, INDONESIAPAPAN KASUS BUKA
CEK STATUS KASUSMU
TANYA GRATIS
DAMPINGIN · TANYA GRATIS, TANPA DAFTARTANYA GRATIS

Autentikasi

API key, scope, batas budget, dan gerbang persetujuan organisasi.

Header

Kirim API key sebagai Bearer token di setiap request:

http
Authorization: Bearer dk_live_<prefix>.<secret>

Bagian sebelum titik adalah prefix publik (untuk mencari key), bagian sesudahnya secret. Dampingin hanya menyimpan hash SHA-256 dari secret, jadi key yang hilang tidak bisa ditampilkan lagi: buat key baru. Key yang tidak ada, salah format, salah secret, atau sudah dicabut menghasilkan 401 UNAUTHORIZED.

Belum tersedia

OAuth belum tersedia. API dan server MCP hanya menerima API key organisasi.

Scope

Scope dipilih saat key dibuat. Request ke endpoint di luar scope key ditolak dengan 403 FORBIDDEN_SCOPE.

ScopeEndpointButuh organisasi disetujui
katalog:bacaGET /v1/services, GET /v1/services/{code}Tidak
status:bacaGET /v1/orders/{id}, GET /v1/cases/{id}, GET /v1/balanceTidak
order:buatPOST /v1/orders, POST /v1/orders/{id}/messages, POST /v1/orders/{id}/acceptYa
kasus:buatPOST /v1/cases, POST /v1/cases/{id}/selectYa
dokumen:buatBelum dipakai endpoint mana punYa

Dashboard mencentang katalog:baca dan status:baca secara default. Beri scope yang benar-benar dibutuhkan agent saja.

Batas budget

  • Batas per order (max_order_budget): order yang harganya melebihi batas ini, atau melebihi max_budget di body request (mana yang lebih kecil), ditolak 402 BUDGET_EXCEEDED.
  • Batas per bulan (monthly_budget): jumlah harga order yang dibuat key ini sejak tanggal 1 bulan berjalan (tidak termasuk dibatalkan dan direfund) ditambah order baru tidak boleh melebihinya, atau 402 MONTHLY_BUDGET_EXCEEDED.
  • Batas per order tidak boleh lebih besar dari batas per bulan. Keduanya diatur saat membuat key.
  • Pemakaian berjalan terlihat di GET /v1/balance:
json
{
  "deposit_idr": 22500000,
  "key": {
    "max_order_budget": 10000000,
    "monthly_budget": 50000000,
    "spent_this_month": 27500000,
    "scopes": ["katalog:baca", "order:buat", "status:baca"]
  }
}

Persetujuan organisasi

Ada dua lapis persetujuan manusia:

  1. Organisasi. Scope yang membelanjakan uang atau membuat pekerjaan (order:buat, kasus:buat, dokumen:buat) hanya jalan untuk organisasi berstatus disetujui. Selain itu: 403 ACCOUNT_PENDING (masih ditinjau) atau 403 ACCOUNT_REJECTED (ditolak atau ditangguhkan). Endpoint baca tetap terbuka.
  2. Order. Order agent dengan harga di atas ambang organisasi (default Rp 5.000.000, bisa diubah owner/admin) dibuat dengan status menunggu_bayar dan approval_required: true. Owner atau admin menyetujui (deposit dipotong, order jadi dibayar) atau menolak (order jadi dibatalkan) di dashboard.

Urutan pemeriksaan

Setiap request ke /v1 diperiksa dengan urutan ini, jadi kode error yang kamu terima menunjukkan tahap mana yang gagal:

  1. Path dan method dikenal (404 NOT_FOUND, 405 METHOD_NOT_ALLOWED).
  2. API key valid (401 UNAUTHORIZED).
  3. Rate limit 60 request per menit per key (429 RATE_LIMITED).
  4. Scope dan status organisasi (403).
  5. Validasi dan aturan bisnis endpoint.

Rotasi dan pencabutan

Owner dan admin bisa mencabut key kapan saja di dashboard (tombol Cabut); request berikutnya dengan key itu langsung 401. Untuk rotasi: buat key baru, pindahkan agent, lalu cabut key lama. Belum ada endpoint API untuk mengelola key.

Menyimpan key untuk agent

  • Satu key per agent atau per lingkungan, supaya batas budget dan pencabutan tidak saling mengganggu.
  • Jangan taruh key di prompt, log, atau repo. Server MCP membaca key dari variabel lingkungan atau header.
SebelumnyaQuickstartBerikutnyaKatalog & harga agent