Basis pengetahuan GetMyBot

Izin akses dan token

Beri program akses ke GetMyBot: buat token pribadi, pilih ruang kerja, dan izinkan tindakan yang diperlukan saja.

Di halaman ini

Token pribadi memungkinkan program mengakses GetMyBot tanpa mengetahui kata sandi Anda. Dalam dokumentasi, token ini disebut PAT (Personal Access Token). Misalnya, melihat daftar bot memerlukan izin bots:read, sedangkan membuat reaksi memerlukan reactions:write.

Saat membuat token, pilih satu ruang kerja dan izin yang diperlukan, yang disebut cakupan akses (scopes). Token hanya berlaku di ruang kerja itu dan tidak dapat melakukan tindakan di luar hak akun Anda. Untuk contoh pertama, lihat Memulai dengan API.

Membuat token

Buat token di bagian token pribadi pada akun Anda. Nilainya hanya ditampilkan sekali. Segera simpan di tempat yang aman. Server hanya menyimpan bentuk hash token, sehingga nilainya tidak dapat ditampilkan lagi. Jika hilang, buat token baru dan hapus yang lama.

Semua token pribadi diawali mbp_.

Mengirim token

Kirim token bersama setiap permintaan melalui header HTTP Authorization dengan format Bearer:

Authorization: Bearer <TOKEN_PRIBADI>

Ganti seluruh <TOKEN_PRIBADI>, termasuk tanda kurung sudutnya, dengan nilai token lengkap yang sudah diawali mbp_. Jangan tambahkan awalan itu lagi. Server MCP hanya menerima token pribadi. Token API proyek yang diawali mb_live_ tidak dapat digunakan untuk MCP.

Sesi di situs web juga menggunakan header Authorization, tetapi isinya berupa token sesi sementara. Untuk integrasi, gunakan token pribadi mbp_.

Ruang kerja yang dipilih untuk token

Satu token berlaku tepat di satu ruang kerja. Secara bawaan, ruang kerja itu milik Anda sendiri. Jika Anda diundang ke ruang kerja orang lain, Anda dapat memilihnya ketika membuat token. Di API, pilih melalui account_id dalam permintaan POST /api/tokens; di situs, gunakan daftar ruang kerja di atas pilihan masa berlaku token. GET /api/account/cabinets menampilkan ruang kerja yang dapat Anda pilih.

Artinya:

  • GET /api/bots hanya menampilkan bot dari ruang kerja yang dipilih, bukan bot dari ruang kerja Anda yang lain.
  • Jika token dipakai untuk bot di ruang kerja lain, API mengirim 404. Respons ini juga tidak memberi tahu apakah ID bot tersebut ada.
  • Token tidak menambah hak Anda. Peran Anda di ruang kerja dan izin untuk bot tertentu tetap menentukan tindakan yang boleh dilakukan.
  • Token untuk ruang kerja orang lain menggunakan hak Anda di ruang kerja itu. Melihat tagihan melalui /api/billing/* memerlukan hak billing.read; membuat proyek memerlukan bots.create. Cakupan token * tidak memberikan hak ruang kerja secara otomatis.
  • Jika akses Anda ke ruang kerja dicabut, token langsung berhenti bekerja mulai permintaan berikutnya.

Ruang kerja yang hanya dapat diakses melalui bot

Untuk setiap ruang kerja, GET /api/account/cabinets menampilkan nilai source:

  • self: ruang kerja milik Anda;
  • account: Anda diberi akses ke ruang kerja, sesuai peran Anda;
  • bot: Anda hanya diberi akses ke satu bot di ruang kerja itu, bukan ke seluruh ruang kerja.

Jika source adalah bot, token dapat mengerjakan tindakan pada bot tersebut sesuai izin Anda. Tindakan untuk seluruh ruang kerja, seperti menghubungkan bot baru atau melihat tagihan, ditolak. REST mengirim 403 dengan {"error":"missing cabinet right"} atau missing cabinet right: <hak> jika hak tertentu tidak ada. Di MCP, pesannya permission denied: missing cabinet right. Contohnya, connect_bot memerlukan bots.create, sedangkan alat tagihan memerlukan billing.read atau billing.write.

Untuk memperoleh hak yang diperlukan, minta pemilik mengundang Anda melalui Akses ruang kerja. Setelah Anda menerima undangan, token yang sama dapat digunakan mulai permintaan berikutnya.

Token yang dibuat sebelum fitur pemilihan ruang kerja tersedia tetap terikat pada ruang kerja Anda sendiri. Jika dahulu token seperti itu dipakai untuk bot yang dibagikan dari ruang kerja lain, buat token tersendiri untuk ruang kerja tersebut.

Cakupan akses (scopes)

Cakupan akses ditulis dalam bentuk sumber:tindakan. Akhiran :read berarti membaca, sedangkan :write berarti mengubah. Cakupan yang tersedia:

CakupanTindakan yang diizinkan
bots:read, bots:writeMembaca dan mengatur bot, sinkronisasi, dan token bot.
reactions:read, reactions:writeMengelola reaksi, impor, memeriksa rumus, hubungan, dan urutan.
labels:read, labels:writeMengelola label pelanggan.
collections:read, collections:writeMengelola koleksi dan isinya.
flows:read, flows:writeMengelola alur.
integrations:read, integrations:writeMengelola integrasi, koneksi, dan data akses.
media:writeMengunggah berkas ke pustaka media.
templates:read, templates:writeMengelola template bot.
settings:read, settings:writeMengelola pengaturan.
subscribers:readMembaca data pelanggan dan riwayat percakapan.
broadcasts:writeMembuat dan mengatur siaran.
stats:readMembaca statistik dan analitik.
billing:readMembaca saldo dan paket.

Cakupan khusus * mencakup semua alamat API publik yang dapat diakses melalui token. Hak akun dan ruang kerja tetap berlaku.

Apa yang dapat dilakukan dengan token?

Token pribadi digunakan untuk alamat API yang membantu membuat dan mengatur bot. Beberapa tindakan hanya tersedia dalam sesi situs web: masuk dan mendaftar, fungsi aplikasi seluler, pembayaran dan isi saldo, pemberitahuan, catatan audit, pesan operator ke pelanggan, webhook masuk, pemberitahuan pembayaran, dan WebSocket. Permintaan dengan token mbp_ ke alamat tersebut ditolak dengan 401 atau 403.

Jika token tidak memiliki cakupan yang diperlukan, API mengirim 403. Lihat Kesalahan API.

Izin untuk fungsi agen AI

  • managed_ai:invoke dan managed_ai:usage:read: menjalankan AI serta membaca pemakaiannya.
  • copilot:use: memakai saran Copilot. Untuk melihat diagnosis diperlukan journey:read; untuk mengubah alur juga diperlukan journey:edit.
  • journey:read dan journey:edit: menganalisis alur dan menjelaskan jalannya tindakan melalui Flow Intelligence dan Explainable Replay.
  • Pengaturan koneksi Meta memakai cakupan integrasi dan bot. Hak atas ruang kerja dan bot yang bersangkutan tetap diperiksa.

MCP memeriksa izin yang sama. Menghubungkan MCP tidak memberi token akses tambahan ke bot atau ruang kerja lain.

Langkah berikutnya