Izin

Sebuah key hanya bisa melakukan yang diberikan kepadanya, dalam pasangan resource:action. Izin tulis sudah mencakup izin baca yang sepadan: key yang boleh mengubah sebuah resource juga boleh melihatnya. Kamu memilih izin saat membuat key di dashboard; beri hanya yang dibutuhkan servermu.

Jenis izin

• Baca (:read) membuat key bisa melihat sebuah resource: mengambil satu, mendaftar semuanya.
• Tulis (:write) membuat key bisa membuat dan mengubahnya, dan sudah mencakup baca.

Izin yang tersedia

Izin	Memperbolehkan
payments:read	Membaca pembayaran (riwayat dan percobaannya), payment link, dan laporan analitik
payments:write	Membuat dan membatalkan pembayaran, membuat dan membatalkan payment link, mensimulasikan pembayaran uji (dan semua yang diperbolehkan payments:read)
invoices:read	Membaca invoice
invoices:write	Membuat, mengubah, menerbitkan, membatalkan, mengirim ulang, dan menghapus invoice. Menerbitkan mengirim email ke pelangganmu di live (dan semua yang diperbolehkan invoices:read)
webhooks:read	Membaca event, jenis event, endpoint webhook, dan pengirimannya
webhooks:write	Membuat, mengubah, menghapus, dan menguji endpoint webhook, serta memutar secret-nya (dan semua yang diperbolehkan webhooks:read)
balances:read	Membaca saldo dan mutasinya, serta laporan statement, buku besar, rekonsiliasi, dan settlement (hanya key merchant)
payouts:read, payouts:write	Disiapkan. Belum ada operasi payout, dan payouts:write hanya untuk key proyek

Operasi dan izin yang dibutuhkan

Operasi	Endpoint	Izin
Lihat akun	GET /v1/account	tidak ada: key sah apa pun
Buat pembayaran	POST /v1/payments	payments:write
Daftar pembayaran	GET /v1/payments	payments:read
Lihat pembayaran	GET /v1/payments/{id}	payments:read
Lihat riwayat pembayaran	GET /v1/payments/{id}/timeline	payments:read
Daftar percobaan pembayaran	GET /v1/payments/{id}/attempts	payments:read
Batalkan pembayaran	POST /v1/payments/{id}/cancel	payments:write
Simulasikan pembayaran	POST /v1/sandbox/payments/{id}/simulate	payments:write
Buat payment link	POST /v1/payment-links	payments:write
Daftar payment link	GET /v1/payment-links	payments:read
Lihat payment link	GET /v1/payment-links/{id}	payments:read
Batalkan payment link	POST /v1/payment-links/{id}/cancel	payments:write
Buat invoice	POST /v1/invoices	invoices:write
Daftar invoice	GET /v1/invoices	invoices:read
Lihat invoice	GET /v1/invoices/{id}	invoices:read
Ubah invoice draf	PUT /v1/invoices/{id}	invoices:write
Hapus invoice draf	DELETE /v1/invoices/{id}	invoices:write
Terbitkan invoice	POST /v1/invoices/{id}/issue	invoices:write
Batalkan invoice	POST /v1/invoices/{id}/void	invoices:write
Kirim ulang invoice	POST /v1/invoices/{id}/resend	invoices:write
Daftar metode pembayaran	GET /v1/payment-methods	tidak ada: key sah apa pun
Lihat batas pembayaran	GET /v1/payment-limits	tidak ada: key sah apa pun
Perkiraan biaya	POST /v1/fee-preview	tidak ada: key sah apa pun
Daftar proyek	GET /v1/projects	tidak ada: key sah apa pun
Lihat proyek	GET /v1/projects/{id}	tidak ada: key sah apa pun
Lihat statement	GET /v1/reports/statement	balances:read
Lihat buku besar	GET /v1/reports/ledger	balances:read
Lihat rekonsiliasi	GET /v1/reports/reconciliation	balances:read
Lihat settlement	GET /v1/reports/settlements	balances:read
Lihat analitik	GET /v1/reports/analytics	payments:read
Lihat saldo	GET /v1/balance	balances:read
Daftar mutasi saldo	GET /v1/balance/movements	balances:read
Daftar jenis event	GET /v1/event-types	webhooks:read
Daftar event	GET /v1/events	webhooks:read
Lihat event	GET /v1/events/{id}	webhooks:read
Daftar pengiriman webhook	GET /v1/webhook-deliveries	webhooks:read
Lihat pengiriman webhook	GET /v1/webhook-deliveries/{id}	webhooks:read
Kirim ulang pengiriman webhook	POST /v1/webhook-deliveries/{id}/resend	webhooks:write
Daftar endpoint webhook	GET /v1/webhook-endpoints	webhooks:read
Buat endpoint webhook	POST /v1/webhook-endpoints	webhooks:write
Lihat endpoint webhook	GET /v1/webhook-endpoints/{id}	webhooks:read
Ubah endpoint webhook	PATCH /v1/webhook-endpoints/{id}	webhooks:write
Hapus endpoint webhook	DELETE /v1/webhook-endpoints/{id}	webhooks:write
Rotasi secret endpoint	POST /v1/webhook-endpoints/{id}/rotate-secret	webhooks:write
Kirim event uji	POST /v1/webhook-endpoints/{id}/test	webhooks:write

Kalau izin tidak dibutuhkan

GET /v1/account, GET /v1/projects, GET /v1/payment-methods, GET /v1/payment-limits, dan POST /v1/fee-preview tidak butuh izin: key sah apa pun bisa memanggilnya, karena semuanya menggambarkan akunmu dan apa yang dijual, bukan sebuah pembayaran. GET /v1/account menjawab dengan izin dari key yang kamu pakai (key.scopes), jadi inilah cara tercepat untuk memeriksa apa yang bisa dilakukan sebuah key.

Tanpa izin

Panggilan yang tidak diizinkan untuk key itu dijawab 403 insufficient_scope, sebelum apa pun dikerjakan:

{
  "error": {
    "type": "authorization_error",
    "code": "insufficient_scope",
    "detail": "This API key does not have the permission this request needs.",
    "documentation_url": "https://docs.baiyar.com/resources/errors/insufficient_scope/"
  },
  "meta": {
    "request_id": "req_…"
  }
}

Dua operasi butuh key merchant, apa pun izinnya: saldo milik merchant, jadi key proyek mendapat 403 forbidden di GET /v1/balance dan GET /v1/balance/movements; dan endpoint webhook untuk seluruh merchant (scope: "merchant") hanya bisa dibuat dengan key merchant.

Praktik terbaik

• Beri tiap key yang paling sedikit yang dibutuhkan: server yang hanya membuat pembayaran butuh payments:write dan tidak yang lain.
• Pakai key terpisah untuk tiap layanan, supaya bocornya satu key tidak memberi banyak.
• Untuk menambah kemampuan sebuah key, buat key baru dengan izin baru lalu putar yang lama sampai berakhir.

Halaman terkait

• Autentikasi
• Ambil API key
• Error