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/botshanya 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 hakbilling.read; membuat proyek memerlukanbots.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:
| Cakupan | Tindakan yang diizinkan |
|---|---|
bots:read, bots:write | Membaca dan mengatur bot, sinkronisasi, dan token bot. |
reactions:read, reactions:write | Mengelola reaksi, impor, memeriksa rumus, hubungan, dan urutan. |
labels:read, labels:write | Mengelola label pelanggan. |
collections:read, collections:write | Mengelola koleksi dan isinya. |
flows:read, flows:write | Mengelola alur. |
integrations:read, integrations:write | Mengelola integrasi, koneksi, dan data akses. |
media:write | Mengunggah berkas ke pustaka media. |
templates:read, templates:write | Mengelola template bot. |
settings:read, settings:write | Mengelola pengaturan. |
subscribers:read | Membaca data pelanggan dan riwayat percakapan. |
broadcasts:write | Membuat dan mengatur siaran. |
stats:read | Membaca statistik dan analitik. |
billing:read | Membaca 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:invokedanmanaged_ai:usage:read: menjalankan AI serta membaca pemakaiannya.copilot:use: memakai saran Copilot. Untuk melihat diagnosis diperlukanjourney:read; untuk mengubah alur juga diperlukanjourney:edit.journey:readdanjourney: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
- Memulai dengan API: permintaan pertama memakai token.
- Kesalahan API: arti
401dan403. - MCP: memakai token yang sama untuk agen AI.